diff --git a/cookbook/creating_a_cms/auto-routing.rst b/cookbook/creating_a_cms/auto-routing.rst index d9b80710..b6caef3c 100644 --- a/cookbook/creating_a_cms/auto-routing.rst +++ b/cookbook/creating_a_cms/auto-routing.rst @@ -1,7 +1,7 @@ Routing and Automatic Routing ----------------------------- -The routes (URLs) to your content will be automatically created and updated +The routes (URIs) to your content will be automatically created and updated using the RoutingAutoBundle. This bundle uses a configuration language to specify automatic creation of routes, which can be a bit hard to grasp the first time you see it. @@ -17,7 +17,7 @@ new route will be linked back to the target content: The paths above represent the path in the PHPCR-ODM document tree. In the next section you will define ``/cms/routes`` as the base path for routes, and subsequently -the contents will be available at the following URLs: +the contents will be available at the following URIs: * **Home**: ``http://localhost:8000/page/home`` * **About**: ``http://localhost:8000/page/about`` @@ -26,22 +26,8 @@ the contents will be available at the following URLs: Installation ~~~~~~~~~~~~ -Ensure that you have the following package installed: - -.. code-block:: javascript - - { - ... - require: { - ... - "symfony-cmf/routing-auto-bundle": "1.0.*@alpha" - }, - ... - } - -.. note:: - - You are installing the bleeding edge version of the routing-auto bundle. +Ensure that you installed the RoutingAutoBundle package as detailed in the :ref:`gettingstarted_installadditionbundles` +section. Enable the routing bundles to your kernel:: @@ -135,88 +121,53 @@ This will: Auto Routing Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create the following file in your applications configuration directory: +First you need to configure the auto routing bundle: .. code-block:: yaml - # app/config/routing_auto.yml cmf_routing_auto: - mappings: - Acme\BasicCmsBundle\Document\Page: - content_path: - pages: - provider: [specified, { path: /cms/routes/page }] - exists_action: use - not_exists_action: create - content_name: - provider: [content_method, { method: getTitle }] - exists_action: auto_increment - not_exists_action: create - - Acme\BasicCmsBundle\Document\Post: - content_path: - blog_path: - provider: [specified, { path: /cms/routes/post }] - exists_action: use - not_exists_action: create - date: - provider: [content_datetime, { method: getDate}] - exists_action: use - not_exists_action: create - content_name: - provider: [content_method, { method: getTitle }] - exists_action: auto_increment - not_exists_action: create + persistence: + phpcr: + enabled: true -This will configure the routing auto system to automatically create and update -route documents for both the ``Page`` and ``Post`` documents. +The above configures the RoutingAutoBundle to work with PHPCR-ODM. -In summary: +You can now proceed to mapping your documents, create the following in your +*bundles* configuration directory: -* The ``content_path`` key represents the parent path of the content, e.g. - ``/if/this/is/a/path`` then the ``content_path`` - represents ``/if/this/is/a``; -* Each element under ``content_path`` represents a section of the URL; -* The first element ``blog_path`` uses a *provider* which *specifies* a - path. If that path exists then it will do nothing; -* The second element uses the ``content_datetime`` provider, which will - use a ``DateTime`` object returned from the specified method on the - content object (the ``Post``) and create a path from it, e.g. - ``2013/10/13``; -* The ``content_name`` key represents the last part of the path, e.g. ``path`` - from ``/if/this/is/a/path``. +.. code-block:: yaml -Now you will need to include this configuration: + # src/Acme/BasicCmsBundle/Resources/config/cmf_routing_auto.yml + Acme\BasicCmsBundle\Document\Page: + uri_schema: /page/{title} + token_providers: + title: [content_method, { method: getTitle } ] -.. configuration-block:: - - .. code-block:: yaml + Acme\BasicCmsBundle\Document\Post: + uri_schema: /post/{date}/{title} + token_providers: + date: [content_datetime, { method: getDate } + title: [content_method, { method: getTitle }] - # app/config/config.yml - imports: - - { resource: routing_auto.yml } +.. note:: - .. code-block:: xml + RoutingAutoBundle mapping bundles are registered automatically when they are named + as above, you may alternatively explicitly declare from where the mappings should be loaded, + see the :doc:`../../bundles/routing_auto/index` documentation for more information. - - - - - - - - .. code-block:: php +This will configure the routing auto system to automatically create and update +route documents for both the ``Page`` and ``Post`` documents. - // src/Acme/BasicCmsBundle/Resources/config/config.php +In summary, for each class: - // ... - $this->import('routing_auto.yml'); +* We defined a ``uri_schema`` which defines the form of the URI which will be + generated. + * Within the schema you place ``{tokens}`` - placeholders for values provided by... +* Token providers provide values which will be substituted into the URI. Here + you use two different providers - ``content_date`` and ``content_method``. + Both will return dynamic values from the subject object itself. -and reload the fixtures: +Now reload the fixtures: .. code-block:: bash diff --git a/cookbook/creating_a_cms/content-to-controllers.rst b/cookbook/creating_a_cms/content-to-controllers.rst index 37a1deb3..8dd51869 100644 --- a/cookbook/creating_a_cms/content-to-controllers.rst +++ b/cookbook/creating_a_cms/content-to-controllers.rst @@ -1,7 +1,45 @@ Controllers and Templates ------------------------- -Go to the URL http://localhost:8000/page/home in your browser - this should be +Make your content route aware +............................. + +In the :doc:`getting-started` section you defined your `Post` and `Page` documents as +implementing the `RoutesReferrersReadInterface`. This interface enables the routing system +to retrieve routes which refer to the object implementing this interface, and this enables +the system to generate a URL (for example when you use ``{{ path(mydocument) }}`` in Twig). + +Earlier we did not have the RoutingBundle installed, so we could not add the mapping. + +Map the ``$routes`` property to contain a collection of all the routes which refer to this +document:: + + // src/AcmeBundle/BasicCmsBundle/Document/ContentTrait.php + + // ... + + trait ContentTrait + { + // ... + + /** + * @PHPCR\Referrers( + * referringDocument="Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route", + * referencedBy="content" + * ) + */ + protected $routes; + + // ... + } + +Now you can call the method ``getRoutes`` on either ``Page`` or ``Post`` and retrieve all the +routes which refer to that document ... pretty cool! + +Route requests to a controller +.............................. + +Go to the URL http://127.0.0.1:8000/page/home in your browser - this should be your page, but it says that it cannot find a controller. In other words it has found the *route referencing the page* for your page but Symfony does not know what to do with it. diff --git a/cookbook/creating_a_cms/getting-started.rst b/cookbook/creating_a_cms/getting-started.rst index 49bd11db..4268cb75 100644 --- a/cookbook/creating_a_cms/getting-started.rst +++ b/cookbook/creating_a_cms/getting-started.rst @@ -4,9 +4,11 @@ Getting Started Initializing the Project ~~~~~~~~~~~~~~~~~~~~~~~~ -First, follow the generic steps in :doc:`../../bundles/phpcr_odm/introduction` +First, follow the generic steps in :doc:`../database/create_new_project_phpcr_odm` to create a new project using the PHPCR-ODM. +.. _gettingstarted_installadditionbundles: + Install Additional Bundles .......................... @@ -23,19 +25,28 @@ section titled "installation". If you intend to complete the entire tutorial you can save some time by adding all of the required packages now. +.. note:: + + The routing-auto bundle is currently unstable, the package versions listed below are required + but are not **stable**. This means that this is a somewhat volatile combination and you should + think twice before deploying to production -- there will be a stable release soon. + +Please ensure that the packages below replace any packages already defined in your ``composer.json`` +file in the previous step. + .. code-block:: javascript { ... require: { ... - "symfony-cmf/routing-auto-bundle": "1.0.*@alpha", - "symfony-cmf/menu-bundle": "1.1.*", + "doctrine/phpcr-bundle": "1.0.0", + "jackalope/jackalope-doctrine-dbal": "1.1.0", + "symfony-cmf/routing-auto-bundle": "dev-master", + "symfony-cmf/menu-bundle": "1.2.*", "sonata-project/doctrine-phpcr-admin-bundle": "1.1.*", - "symfony-cmf/tree-browser-bundle": "1.1.*", + "symfony-cmf/tree-browser-bundle": "1.1.x-dev as 1.0", "doctrine/data-fixtures": "1.0.*", - - "doctrine/phpcr-odm": "1.1.*", "phpcr/phpcr-utils": "1.1.*", "doctrine/phpcr-bundle": "1.1.*", "symfony-cmf/routing-bundle": "1.2.*", @@ -110,7 +121,7 @@ to reduce code duplication:: protected $parent; /** - * @PHPCR\NodeName() + * @PHPCR\Nodename() */ protected $title; @@ -119,12 +130,6 @@ to reduce code duplication:: */ protected $content; - /** - * @PHPCR\Referrers( - * referringDocument="Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route", - * referencedBy="content" - * ) - */ protected $routes; public function getId() @@ -267,8 +272,8 @@ configuration: .. code-block:: xml - + homepage = $homepage; } + + public function setId($id) + { + $this->id = $id; + } } Initializing the Site Document @@ -85,6 +90,7 @@ node:: use Doctrine\Bundle\PHPCRBundle\Initializer\InitializerInterface; use PHPCR\Util\NodeHelper; use Doctrine\Bundle\PHPCRBundle\ManagerRegistry; + use Acme\BasicCmsBundle\Document\Site; class SiteInitializer implements InitializerInterface { @@ -102,7 +108,7 @@ node:: return; } - $site = new Acme\BasicCmsBundle\Document\Site(); + $site = new Site(); $site->setId($this->basePath); $dm->persist($site); $dm->flush(); @@ -178,12 +184,13 @@ follows: ->addTag('doctrine_phpcr.initializer', array('name' => 'doctrine_phpcr.initializer') ; -Now empty your repository and then reinitialize it: +Now empty your repository, reinitialize it and reload your fixtures: .. code-block:: bash $ php app/console doctrine:phpcr:node:remove /cms $ php app/console doctrine:phpcr:repository:init + $ php app/console doctrine:phpcr:fixtures:load and verify that the ``cms`` node has been created correctly, using the ``doctrine:phpcr:node:dump`` command with the ``props`` flag: diff --git a/cookbook/creating_a_cms/sonata-admin.rst b/cookbook/creating_a_cms/sonata-admin.rst index 1badbc65..ed852482 100644 --- a/cookbook/creating_a_cms/sonata-admin.rst +++ b/cookbook/creating_a_cms/sonata-admin.rst @@ -7,18 +7,9 @@ of the SonataDoctrinePHPCRAdminBundle_. Installation ~~~~~~~~~~~~ -Ensure that you have the following package installed: - -.. code-block:: javascript - - { - ... - require: { - ... - "sonata-project/doctrine-phpcr-admin-bundle": "1.1.*", - }, - ... - } +Ensure that you installed the ``sonata-project/doctrine-phpcr-admin-bundle`` +package as detailed in the :ref:`gettingstarted_installadditionbundles` +section. Enable the Sonata related bundles to your kernel:: @@ -146,7 +137,14 @@ and publish your assets (remove ``--symlink`` if you use Windows!): $ php app/console assets:install --symlink web/ -Great, now have a look at http://localhost:8000/admin/dashboard +Now start a local webserver: + +.. code-block:: bash + + $ php app/console server:run + + +That works? Great, now have a look at http://127.0.0.1:8000/admin/dashboard No translations? Uncomment the translator in the configuration file: @@ -475,6 +473,12 @@ Enable the CmfTreeBundle and the FOSJsRoutingBundle in your kernel:: } } +Now publish your assets again: + +.. code-block:: bash + + $ php app/console assets:install --symlink web/ + Routes used by the tree in the frontend are handled by the FOSJsRoutingBundle. The relevant routes are tagged with the ``expose`` flag, they are available automatically. However, you need to load the routes of the TreeBundle @@ -523,7 +527,8 @@ and the FOSJsRoutingBundle: return $collection; Add the tree block to the ``sonata_block`` configuration and tell sonata -admin to display the block: +admin to display the block (be careful to *add* to the existing configuration and +not to create another section!): .. configuration-block:: diff --git a/cookbook/creating_a_cms/the-frontend.rst b/cookbook/creating_a_cms/the-frontend.rst index 47ce8fe2..a5657241 100644 --- a/cookbook/creating_a_cms/the-frontend.rst +++ b/cookbook/creating_a_cms/the-frontend.rst @@ -8,18 +8,8 @@ using the Twig helper of the `KnpMenuBundle`_. Installation ............ -Ensure that the following package is installed: - -.. code-block:: javascript - - { - ... - require: { - ... - "symfony-cmf/menu-bundle": "1.1.*" - }, - ... - } +Ensure that you installed the ``symfony-cmf/menu-bundle`` package as detailed in the :ref:`gettingstarted_installadditionbundles` +section. Add the CMF `MenuBundle`_ and its dependency, `CoreBundle`_, to your kernel:: diff --git a/cookbook/database/create_new_project_phpcr_odm.rst b/cookbook/database/create_new_project_phpcr_odm.rst new file mode 100644 index 00000000..dc9a23a5 --- /dev/null +++ b/cookbook/database/create_new_project_phpcr_odm.rst @@ -0,0 +1,158 @@ +.. index:: + single: PHPCR-ODM, Creating a New Project + +Create a New Project with PHPCR-ODM +=================================== + +This article will show you how to create a new Symfony project from the +`Symfony Standard Edition`_ using PHPCR-ODM instead of (or in addition to) the +`Doctrine ORM`_. + +It is assumed that you have `installed composer`_. + +.. note:: + + This walkthrough is intended to get you off the ground quickly, for more + detailed documentation on integrating the PHPCR-ODM bundle see + the documentation for the :doc:`../../bundles/phpcr_odm/index`. + +General Instructions using Jackalope Doctrine DBAL +-------------------------------------------------- + +The `Jackalope`_ Doctrine DBAL backend will use `Doctrine DBAL`_ to store the +content repository. + +**Step 1**: Create a new Symfony project with composer based on the standard edition: + +.. code-block:: bash + + $ php composer.phar create-project symfony/framework-standard-edition / --no-install + +**Step 2**: Add the required packages to ``composer.json``: + +.. code-block:: javascript + + { + ... + "require": { + ... + "doctrine/phpcr-bundle": "1.0.0", + "doctrine/phpcr-odm": "1.0.*", + "jackalope/jackalope-doctrine-dbal": "1.0.0" + } + } + + + +**Step 3**: (*optional*) Remove the Doctrine ORM: + +* Remove the ``doctrine\orm`` package from ``composer.json``; +* Remove the ``orm`` section from ``app/config/config.yml``. + +**Step 4**: Add the DoctrinePHPCRBundle to the ``AppKernel``:: + + // app/AppKernel.php + + // ... + class AppKernel extends Kernel + { + public function registerBundles() + { + $bundles = array( + // ... + new Doctrine\Bundle\PHPCRBundle\DoctrinePHPCRBundle(), + ); + + // ... + } + } + +**Step 5**: Modify ``parameters.yml.dist``, adding the required PHPCR-ODM settings: + +.. code-block:: yaml + + # app/config/parameters.yml.dist + parameters: + # ... + phpcr_backend: + type: doctrinedbal + connection: default + phpcr_workspace: default + phpcr_user: admin + phpcr_pass: admin + +.. note:: + + You are modififying ``parameters.yml.dist`` and not ``paramaters.yml``. + This is because the Standard Edition will use this file as a template when + updating the configuration. + +**Step 6**: Add the Doctrine PHPCR configuration to the main application configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # ... + doctrine_phpcr: + # configure the PHPCR session + session: + backend: "%phpcr_backend%" + workspace: "%phpcr_workspace%" + username: "%phpcr_user%" + password: "%phpcr_pass%" + # enable the ODM layer + odm: + auto_mapping: true + auto_generate_proxy_classes: "%kernel.debug%" + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + $container->loadFromExtension('doctrine_phpcr', array( + 'session' => array( + 'backend' => '%phpcr_backend%', + 'workspace' => '%phpcr_workspace%', + 'username' => '%phpcr_username%', + 'password' => '%phpcr_password%', + ), + 'odm' => array( + 'auto_mapping' => true, + 'auto_generate_proxy_classes' => '%kernel.debug%', + ), + )); + +**Step 7**: Run ``composer install``: + +.. code-block:: bash + + $ composer install + +After installing the packages composer will ask you to confirm or modify the +default parameters defined in ``parameters.yml.dist`` and then generate the +``parameters.yml`` file. + +Your should now be all set to start using PHPCR-ODM in your project! + +.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard +.. _`Doctrine ORM`: https://github.com/doctrine/doctrine2 +.. _`Apache Jackrabbit`: https://jackrabbit.apache.org +.. _`Jackalope`: https://github.com/jackalope/jackalope +.. _`Doctrine DBAL`: https://github.com/doctrine/dbal +.. _`installed composer`: http://getcomposer.org/doc/00-intro.md#system-requirements diff --git a/cookbook/index.rst b/cookbook/index.rst index 56be9f7d..55ea4b4e 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -9,6 +9,7 @@ The Cookbook database/choosing_phpcr_implementation database/running_jackrabbit database/doctrine_cache + database/create_new_project_phpcr_odm editions/cmf_sandbox editions/cmf_core exposing_content_via_rest diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 9314d991..82265ff2 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -4,6 +4,7 @@ * :doc:`database/choosing_phpcr_implementation` * :doc:`database/running_jackrabbit` * :doc:`database/doctrine_cache` + * :doc:`database/create_new_project_phpcr_odm` * **Editions**