Twig macros VS includes?

Question

I can't really understand the difference between macros and includes in Twig: both seems to do the same stuff, that is take some variables and output something.

What's the difference and why you use macro or include?

Answer 1

With includes, you would include an entire template, verbatim. That template would have access to any template variables currently in scope.

With macros, you are defining a kind of function within Twig (not to be confused with a Twig function, which can access other application logic, not just data passed into templates) that can render a particular component given appropriate objects. So you could have a macro for rendering, say, a shopping list which takes a shopping list as a parameter - and you could then reuse this macro without worrying whether you'd passed the data into the template in the same way elsewhere. Variables not explicitly passed into the macro would not be within scope within that macro.

A macro should really do one specific task to take some data and render a reusable component. An include can comprise any chunk of things - it's a lot more up to you. The extensible nature of the way Twig templates work, as opposed to something like Smarty, means that you are likely to use includes less, by design - but there can still be use cases where it will be the easiest way of avoiding duplication in your templates.