The Big Picture
The Big Picture¶
Start using the Symfony CMF in 10 minutes! This chapter will walk you through the base concepts of the Symfony CMF and get you started with it.
It's important to know that the Symfony CMF is a collection of bundles which provide common functionality needed when building a CMS with the Symfony Framework. Before you read further, you should at least have a basic knowledge of the Symfony Framework. If you don't know Symfony, start by reading the Symfony Framework Quick Tour.
Solving the framework versus CMS dilemma¶
Before starting a new project, there is a difficult decision on whether it will be based on a framework or on a CMS. When choosing to use a framework, you need to spend much time creating CMS features for the project. On the other hand, when choosing to use a CMS, it's more difficult to build custom application functionality. It is impossible or at least very hard to customize the core parts of the CMS.
The CMF is created to solve this framework versus CMS dilemma. It provides bundles, so you can easily add CMS features to your project. But it also provides flexibility and in all cases you are using the framework, so you can build custom functionality the way you want. This is called a decoupled CMS.
The bundles provided by the Symfony CMF can work together, but they are also able to work standalone. This means that you don't need to add all bundles, you can decide to only use one of them (e.g. only the RoutingBundle or the MediaBundle).
Downloading the Symfony CMF Standard Edition¶
When you want to start using the CMF for a new project, you can download the Symfony CMF Standard Edition. The Symfony CMF Standard Edition is similair to the Symfony Standard Edition, but contains and configures essential Symfony CMF bundles. It also adds a very simple bundle to show some of the basic Symfony CMF features.
The best way to download the Symfony CMF Standard Edition is using Composer:
$ php composer.phar create-project symfony-cmf/standard-edition <path-to-install>
Setting up the Database¶
Now, the only thing left to do is setting up the database. This is not something you are used to doing when creating Symfony applications, but to make a lot of things configurable using an admin, the Symfony CMF needs a database.
To get quickly started, it is expected that you have enabled the sqlite extension. After that, run these commands:
1 2 3 4
$ php app/console doctrine:database:create $ php app/console doctrine:phpcr:init:dbal $ php app/console doctrine:phpcr:repository:init $ php app/console doctrine:phpcr:fixtures:load
You are going to learn more about the Database layer of the Symfony CMF later in the Quick Tour.
The Request Flow¶
When you have at least PHP 5.4, use the
server:run command to run a
local server for the demo. Otherwise, use a localhost and prefix the URLs
Now the standard edition is ready to use, navigate to the homepage
http://localhost:8000/) to see the demo:
You see that we already have a complete website in our demo. Let's take a closer look at the request flow for a Symfony CMF application:
First of all, you see a typical symfony request flow following the white
blocks. It creates a
Request object which will be passed to a router,
which executes the controller and that controller uses models to generate a
view to put in the response.
On top of this, the CMF adds the green blocks. In the coming sections, you'll learn more about these seperately.
Before creating the CMF, the team had done a lot of research on which database to use. They ended up finding JCR, a Content Repository for Java. Together with some other developers they created PHPCR, a PHP port of the JCR specification.
PHPCR uses a directory-like structure. It stores elements in a big tree. Elements have a parent and can have children.
Although PHPCR is the first choice of the CMF team, the bundles are not tied to a specific storage system. Some bundles also provide ORM integration and you can also add your own models easily.
In Symfony, the routes are stored in a configuration file. This means only a developer can change routes. In a CMS, you want the admin to change the routes of their site. This is why the Symfony CMF introduces a DynamicRouter.
The DynamicRouter loads some routes which possibly match the request from the database and then tries to find an exact match. The routes in the database can be edited, deleted and created using an admin interface, so everything is fully under the control of the admin.
Because you may also want other Routers, like the normal Symfony router, the
CMF also provides a
ChainRouter. A chain router contains a chain of other
routers and executes them in a given order to find a match.
Using a database to store the routes makes it also possible to reference other documents from the route. This means that a route can have a Content object.
You'll learn more about the router in the next chapter of the Quick Tour.
When a Route matches, a Controller is executed. This Controller normally just gets the Content object from the Route and renders it. Because it is almost always the same, the CMF uses a generic Controller which it will execute. This can be overriden by setting a specific controller for a Route or Content object.
Adding a New Page¶
Now you know the request flow, you can start adding a new page. In the Symfony
CMF Standard Edition, the data is stored in data files, which are loaded when
doctrine:phpcr:fixtures:load command. To add a new page, you
just need to edit such a data file, which is located in the
1 2 3 4 5 6 7 8 9
# src/Acme/MainBundle/Resources/data/page.yml static: # ... quick_tour: name: "quick_tour" label: "Quick Tour" title: "Reading the Quick Tour" body: "I've added this page while reading the quick tour"
After this, you need to run the
doctrine:phpcr:fixtures:load to reflect
the changes on the database and after refreshing, you can see your new page!
You may already noticed the big black bar at the top of the site:
This bar is generated by the Create.js library. The Symfony CMF integrates the CreatePHP and Create.js libraries using a CreateBundle. This enables you to edit a page using a full WYSIWYG editor when you are reading the page.
Now you can change the content of our new page using Create.js:
After clicking "save", the changes are saved using the CreateBundle and the content is updated.
Congratulations! You've come to the end of your first introduction into the Symfony CMF. There is a lot more to discover, but you should already see how the Symfony CMF tries to make your life as a developer better by providing some CMS bundles. If you want to discover more, you can dive into the next section: "The Model".
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.