This document is not meant to be a comprehensive guide to either= Symfony 2 or eZ Publish 5, but to give an overview of how common concepts = and tasks used in older versions translate into the new one.
[=20
] [=20
Glossary ] [=20
New names of exist=
ing concepts: ] [=20
New concepts: ] [=20
Existing concepts FAQ =
] [=20
Settings ] [=20
Siteaccesses ] [=20
Urls ] [=20
Designs ] [=20
Templates (Twig) ] [=20
i18n ] [=20
Loading CSS and js ] [=20
Caching ] [=20
Using 4-in-5 ] [=20
Extensions ] [=20
Debugging ] [=20
Testing ]
Looking for 4.x documentation ?
You will find the 4.x documentation in the legacy part of the documentation.
Glossary
N= ew names of existing concepts:
4.x |
5.x |
| (Content) Class | Content Type |
| (Content) Class Group | Content Type Group |
| (Content) Class Attribute | Field Definition |
| (Content) Object | Content (i= tem) |
| (Content Object) Version | Version Info |
(Content Object) Attribute |
Field |
| (Content Object) Attribute content | Field Value |
Datatype |
Field Type |
Node |
Location |
The reason for renaming some of the concepts in eZ Publish 5.x= was to use terms which might be more familiar to users coming from other C= MS and avoid confusion with terms used in OOP programming.
New concepts:
You can also refer to Symfony glossary page a=
s many of the following concepts are the same or taken from Symfony.
5.x
Description
Co=
ntroller
An OOP version of what was called "mo=
dule" in 4.x, should extend eZ\Bundle\=
EzPublishCoreBundle\Controller.
A good start is to read Symfony documentation on this topic.
Ac=
tion
The method on the Controller, similarly to wh=
at was referred to as "view" in 4.x, contains business log=
ic bootstrap (business logic should be done in services).
View
The template that=
displays the result of the "action", can be either .twig (default) or .php=
.
Note that Twig is highly recommended as it has =
eZ Publish specific helpers.
Service
A Service is a generic term for an=
y PHP object that performs a specific task and thus contains business logic=
. Services are instantiated and maintained a the service container=
.
Service Container=
A Service Container, also known as=
a Dependency Injection Container, is a special object that manage=
s the instantiation of services inside an application. Instead of creating =
services directly, the developer trains the service container (via configur=
ation) on how to create the services.
See Symfony documentation on the service container.
Render
A function that allows you to =
Embed other controller calls, as in Hierarchically render oth=
er controllers and embed it in your result. This effectively removes the ne=
ed for having business logic in template using fetch funct=
ions, session management and so on.
Bu=
ndle
An "extension" in Symfony Framework and hence the extensions of eZ P=
ublish 5.x kernel.
Console
ezpublish/console is =
the starting point of all console commands in Symfony2 (referred to as app/console in Symfony2 documentation) and eZ Publish 5.x kernel, =
use php ezpublish/console -h from the root of your install usi=
ng command line to get started.
web/<=
/span>
The public folder of your site, two console c=
ommands exists to symlink/hard-copy Bundles and Legacy as=
sets respectively.
Front controllers (index.php/index_dev.php) can be mo=
dified to fit your needs.
ezpublish/
The application folder (aka =
app/ =
in the Symfony documentation).
It contains the main Kernel class wh=
ere you can declare the bundles you want to use. You will also find c=
ache/, logs/ and main config/ folders. It =
can also contain application-level resource files, such as global templates=
(ezpublish/Resources/).
src/
This is where your application code stands (fro=
m your own bundles)
vendor/
In this directory stand all your d=
ependencies (3rd party bundles/libs, eZ Publish codebase, Symfony codebase.=
..)
Existing concepts FAQ
Se=
ttings
You can also refer to Symfony glossary page a= s many of the following concepts are the same or taken from Symfony.
5.x |
Description |
Co= ntroller |
An OOP version of what was called "mo=
dule" in 4.x, should extend |
Ac= tion |
The method on the Controller, similarly to wh= at was referred to as "view" in 4.x, contains business log= ic bootstrap (business logic should be done in services). |
| View | The template that=
displays the result of the "action", can be either .twig (default) or .php=
. Note that Twig is highly recommended as it has = eZ Publish specific helpers. |
| Service | A Service is a generic term for an= y PHP object that performs a specific task and thus contains business logic= . Services are instantiated and maintained a the service container= . |
| Service Container= | A Service Container, also known as=
a Dependency Injection Container, is a special object that manage=
s the instantiation of services inside an application. Instead of creating =
services directly, the developer trains the service container (via configur=
ation) on how to create the services. See Symfony documentation on the service container. |
| Render | A function that allows you to = Embed other controller calls, as in Hierarchically render oth= er controllers and embed it in your result. This effectively removes the ne= ed for having business logic in template using fetch funct= ions, session management and so on. |
Bu= ndle |
An " |
| Console | ezpublish/console is =
the starting point of all console commands in Symfony2 (referred to as php ezpublish/console -h from the root of your install usi=
ng command line to get started. |
| web/<= /span> | The public folder of your site, two console c=
ommands exists to symlink/hard-copy Bundles and Legacy as=
sets respectively. |
| ezpublish/ | The application folder (aka =
app/ =
in the Symfony documentation). It contains the main Kernel class wh= ere you can declare the bundles you want to use. You will also find c=
ache/, logs/ and main config/ folders. It =
can also contain application-level resource files, such as global templates=
(ezpublish/Resources/). |
| src/ | This is where your application code stands (fro= m your own bundles) |
| vendor/ | In this directory stand all your d= ependencies (3rd party bundles/libs, eZ Publish codebase, Symfony codebase.= ..) |
New-style settings:
In a single yml file: ezpublish.yml for eZ Publish,= config.yml for other bundles (it is possible to import other files from= here as well).
Note that it's possible to specialize settings for s= pecific environments (e.g.ezpublish_dev.yml,config_dev= .yml)3 scopes (global =3D=3D override; = extension scope is gone)
Order of precedence between extensions (bundles) is set by bundle lo= ading order.
Runtime siteaccess configuration is resolved through the ConfigResolver service.
- Some notes about generic (non-eZ) settings for Symfony=
- Symfony supports 3 formats for config files: yml,
- A single configuration file exists: config.yml (at lea= st, in the final, compiled version, many files exist on disk)
- A configuration file can include another one via the imports statement =
(e.g.
config_dev.ymlwould importconfig.yml) - When creating a bundle, it is not sufficient to add a config file to it=
, the developer needs to specify that it is to be loaded (either via an imp=
ort statement from app/config/config.yml or via a ServiceContainer extensio=
n in php).
Note that if you use the generator bundle command, all neede= d code will be automatically generated for you.
- Symfony supports 3 formats for config files: yml,
Siteaccesses
See http://confluence.ez.no/displa= y/EZP/Siteaccess+Matching
Mostly unchanged
Better way of not duplicating settings: "groups" of siteaccesses
=- Siteaccess settings specializes siteaccess group settings.
New way to define siteaccess: via environment variable (super-fast)<= /p>
Q: Apart from host url a= nd port, are any other matchers available (host+url, =E2=80=A6)
A: working on an improve= d fleximatcher witch will be part of 5.1, this includes host+uri combined m= atching
- Possible now to define custom siteaccess matchers.
Urls
More flexible routing system.
View parameters are still present.
Configuration done in yml file.
Making params optional is done by giving them a default value in the=
config file
More flexible routing system.
View parameters are still present.
Configuration done in yml file.
Making params optional is done by giving them a default value in the= config file
Q: How is the siteaccess= part of urls managed (standard Sf code has no concept for this)?
A: The eZP stack uses an= enhanced router. This is transparent to developers.
Q: Support for link= ing across siteaccess?
A: Yes, Language switcher
Des= igns
Q: How is the concept of designs + fallback suppor= ted ?
A: Planned for 5.future. Might reuse an Sf bundle = from Liip which allows themes (theme =3D=3D = design).
Side question: Can a tpl in one bundle override a t= pl from another one?
A: Yes, but via bundle inheritance a bundle can hav= e only 1 child =E2=80=93 clearly not powerful enough compared to eZP4, but = there seems to be progress in Symfony about improving this.
Templates (Twig)
Twig is a templating engine, used in the templates. eZ Publish Platform = provides Twig helpers and Twig functions. You can also add your own Twig= helpers and functions.
For extending Twig, refer to Twig develo= per documentation and = Symfony cookbook.
i18n
Refer to the translation section in Symfo= ny documentation.
Loading CSS and js
Best practice is to use Ass= etic.
Cac= hing
Content cache is fully Http cache.
Q: How to clear caches f= or eZ Publish 5? Is there a single action to clear caches for both stacks?<= /p>
A: Content (Http) cache =
is purged at publish time or from admin interface. You can use the ca=
che:clear command to clear all Symfony cache and in 'dev' environmen=
t is disabled (see Symfony do=
c on environments) . No unified command yet.
Using 4-in-5
Q: Will it always be pos= sible to run the Legacy Stack as a standalone app?
A: Yes.
Q: Is there any rewrite = rule needed to access var/storage/images of old stack from within the vhost= of the new stack?
A: No, this is achieved =
by symlinking to web/ the design/, =
extension/, share/ and var/ director=
ies of the eZ Publish legacy stack (done via ezpublish:legacy:assets_=
install script).
The official name for the eZ Publish 4.x =
stack included within eZ Publish 5.x is not eZ Publish 4.x but eZ Publish L=
egacy (+"Stack" in case of eZ Publish+extensions).
= Extensions
Q: Implemented as bundle= s?
A: Yes.
Q: Declared as services = with a special tag or naming convention? (see e.g. How twig registers stuff= ).
A: Reuse as much as= possible from Sf, do not enforce standards unless needed.
Q: Will need naming conv= ention?
Q: Installed via compose= r?
A: Yes.
Q: What part of a =
website to put in ezpublish/, what part to put in src/? (equivalent of eZ =E2=80=9Call in extension=E2=80=9D dev
A: ezpublish/ is for global configuration/templates, src/ is for site-spe=
cific developments.
-
ezpublish_legacy/is at root level because it is considere= d as an application in itself.All current extensions will be renamed with= LS suffix (for Legacy Stack) to distinguish them from new implementations.=
Q: Best practices for naming php classes (filenames and directories)?
A: Follow PSR-0, with=
namespaces. Debug toolbar + profiler =3D=3D=3D DebugOutput More info: http://symfony.com/doc/curre=
nt/book/internals.html Sending log messages: Refer to Symfony documentation on testing=
and PHPUnit.
See http://symfony.com/doc/2.0/cookbook/bundles/best_practices.html<=
/p>
D=
ebugging
$logger =3D $this->get('logger');
$logger->info('We just got the logger');
$logger->err('An error occurred');
Tes=
ting