From a13aac05285ab978e1aa096ea0cdb6cbc9e1816a Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Tue, 24 Jan 2017 17:54:24 +0100 Subject: [PATCH] change doc to best practices --- bundles/seo/alternate_locale.rst | 14 ++++--- bundles/seo/configuration.rst | 66 +++++++++++++++-------------- bundles/seo/error_pages.rst | 23 ++++++----- bundles/seo/extractors.rst | 15 ++++--- bundles/seo/introduction.rst | 54 +++++++++++++----------- bundles/seo/seo_aware.rst | 46 ++++++++++----------- bundles/seo/sitemap.rst | 71 +++++++++++++++++--------------- bundles/seo/twig.rst | 2 +- 8 files changed, 155 insertions(+), 136 deletions(-) diff --git a/bundles/seo/alternate_locale.rst b/bundles/seo/alternate_locale.rst index 1b7e5aed..3e2480f0 100644 --- a/bundles/seo/alternate_locale.rst +++ b/bundles/seo/alternate_locale.rst @@ -46,9 +46,10 @@ Enable alternate locale support: .. code-block:: php - $container->loadFromExtension('cmf_seo', array( + // app/config/config.php + $container->loadFromExtension('cmf_seo', [ 'alternate_locale' => true, - )); + ]); If you are using PHPCR-ODM, enabling ``phpcr: ~`` in the seo bundle configuration will activate a listener that extracts the alternate locales @@ -96,11 +97,12 @@ use your custom alternate locale provider instead of the default one. Set the .. code-block:: php - $container->loadFromExtension('cmf_seo', array( - 'alternate_locale' => array ( + // app/config/config.php + $container->loadFromExtension('cmf_seo', [ + 'alternate_locale' => [ 'provider_id' => 'alternate_locale.provider', - ), - )); + ], + ]); .. versionadded:: 1.2 When :doc:`Sitemaps ` are enabled, alternate locales are also diff --git a/bundles/seo/configuration.rst b/bundles/seo/configuration.rst index aa3b8588..1a9cd3f0 100644 --- a/bundles/seo/configuration.rst +++ b/bundles/seo/configuration.rst @@ -42,14 +42,15 @@ Configuration .. code-block:: php - $container->loadFromExtension('cmf_seo', array( - 'persistence' => array( - 'phpcr' => array( + // app/config/config.php + $container->loadFromExtension('cmf_seo', [ + 'persistence' => [ + 'phpcr' => [ 'enabled' => false, 'manager_name' => null, - ), - ), - )); + ], + ], + ]); ``enabled`` *********** @@ -139,8 +140,8 @@ manually or disable the content listener. defaults: default_change_frequency: always templates: - html: CmfSeoBundle:Sitemap:index.html.twig - xml: CmfSeoBundle:Sitemap:index.xml.twig + html: :sitemap/index.html.twig + xml: ::sitemap:index.xml.twig configurations: sitemap: ~ @@ -164,20 +165,20 @@ manually or disable the content listener. .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'sitemap' => array( + $container->loadFromExtension('cmf_seo', [ + 'sitemap' => [ 'enabled' => true, - 'defaults' => array( - 'templates' => array( + 'defaults' => [ + 'templates' => [ 'html' => 'CmfSeoBundle:Sitemap:index.html.twig', 'xml' => 'CmfSeoBundle:Sitemap:index.xml.twig', - ), - ), - 'configurations' => array( + ], + ], + 'configurations' => [ 'sitemap' => null, - ), - ), - )); + ], + ], + ]); ``enabled`` """"""""""" @@ -246,7 +247,7 @@ Extension. ~~~~~~~~ ``data_class`` -""""""""""""""" +"""""""""""""" ``seo_metadata`` **************** @@ -259,8 +260,8 @@ Extension. Configures the class to use when creating new ``SeoMetadata`` objects using the :ref:`SeoMetadata form type `. -When the `phpcr`_ persistence layer is enabled, this defaults to -``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata``. +When the :doc:`PHPCR-ODM <../phpcr_odm/introduction>` persistence layer is enabled, +this defaults to ``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata``. .. _bundles-seo-config-error: @@ -346,13 +347,13 @@ routes, use: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'error' => array( - 'exclusion_rules' => array( - array('path' => '^/admin'), - ), - ), - )); + $container->loadFromExtension('cmf_seo', [ + 'error' => [ + 'exclusion_rules' => [ + ['path' => '^/admin'], + ], + ], + ]); ``alternate_locale`` ~~~~~~~~~~~~~~~~~~~~ @@ -382,12 +383,13 @@ routes, use: .. code-block:: php - $container->loadFromExtension('cmf_seo', array( - 'alternate_locale' => array ( + // app/config/config.php + $container->loadFromExtension('cmf_seo', [ + 'alternate_locale' => [ 'enabled' => true, 'provider_id' => app.alternate_locale.provider, - ), - )); + ], + ]); ``enabled`` """"""""""" diff --git a/bundles/seo/error_pages.rst b/bundles/seo/error_pages.rst index e46134f7..5b290759 100644 --- a/bundles/seo/error_pages.rst +++ b/bundles/seo/error_pages.rst @@ -46,9 +46,9 @@ controller: .. code-block:: php // app/config/config.php - $container->loadFromExtension('twig', array( + $container->loadFromExtension('twig', [ 'exception_controller' => 'cmf_seo.error.suggestion_provider.controller:showAction', - )); + ]); .. seealso:: @@ -99,12 +99,12 @@ You can enable these in your config: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'error' => array( + $container->loadFromExtension('cmf_seo', [ + 'error' => [ 'enable_parent_provider' => true, 'enable_sibling_provider' => true, - ), - )); + ], + ]); .. tip:: @@ -137,7 +137,7 @@ assume you always want to suggest the homepage, the provider looks like:: // somehow get the Route instance of the homepage route (e.g. by quering the database) $homepageRoute = ...; - return array($homepageRoute); + return [$homepageRoute]; } } @@ -150,7 +150,7 @@ Now, register this new class as a service and tag it as # app/config/services.yml services: - app.suggestions.hompage: + app.hompage_suggestions: class: AppBundle\Seo\HomepageSuggestionProvider tags: - { name: cmf_seo.suggestion_provider } @@ -165,7 +165,7 @@ Now, register this new class as a service and tag it as > - @@ -177,11 +177,12 @@ Now, register this new class as a service and tag it as .. code-block:: php // app/config/services.php + use AppBundle\Seo\HomepageSuggestionProvider; use Symfony\Component\DependencyInjection\Definition; - $definition = new Definition('AppBundle\Seo\HomepageSuggestionProvider'); + $definition = new Definition(HomepageSuggestionProvider::class); $definition->addTag('cmf_seo.suggestion_provider'); - $container->setDefinition('app.suggestions.homepage', $definition); + $container->setDefinition('app.hompage_suggestions', $definition); The tag allows a ``group`` attribute, in order to group suggested links. diff --git a/bundles/seo/extractors.rst b/bundles/seo/extractors.rst index 048573c1..169ee2a8 100644 --- a/bundles/seo/extractors.rst +++ b/bundles/seo/extractors.rst @@ -69,12 +69,12 @@ description, you can implement both interfaces and your result will be:: public function getSeoExtras() { - return array( - 'property' => array( + return [ + 'property' => [ 'og:title' => $this->title, 'og:description' => $this->description, - ), - ); + ], + ]; } } @@ -89,6 +89,7 @@ create a class which implements the ``SeoExtractorInterface`` and tag it with .. code-block:: yaml + # app/config/config.yml services: extractor.custom: class: "AppBundle\Extractor\MyCustomExtractor" @@ -97,6 +98,7 @@ create a class which implements the ``SeoExtractorInterface`` and tag it with .. code-block:: xml + register('extractor.custom', 'AppBundle\Extractor\MyCustomExtractor') + // app/config/config.php + use AppBundle\Extractor\MyCustomExtractor; + + $container->register('extractor.custom', MyCustomExtractor::class) ->addTag('cmf_seo.extractor') ; diff --git a/bundles/seo/introduction.rst b/bundles/seo/introduction.rst index d22e9b3a..3609836b 100644 --- a/bundles/seo/introduction.rst +++ b/bundles/seo/introduction.rst @@ -18,11 +18,11 @@ kernel as well:: // ... public function registerBundles() { - $bundles = array( + $bundles = [ // ... new Sonata\SeoBundle\SonataSeoBundle(), new Symfony\Cmf\Bundle\SeoBundle\CmfSeoBundle(), - ); + )]; // ... @@ -60,17 +60,17 @@ The simplest use of this bundle would be to just set some configuration to the .. code-block:: php // app/config/config.php - $container->loadFromExtension('sonata_seo', array( - 'page' => array( + $container->loadFromExtension('sonata_seo', [ + 'page' => [ 'title' => 'Page's default title', - 'metas' => array( - 'name' => array( + 'metas' => [ + 'name' => [ 'description' => 'default description', 'keywords' => 'default, key, other', - ), - ), - ), - )); + ], + ], + ], + ]); This sets default values for the ``SeoPage`` value object. You can later update that object with more precise information. It is available as service @@ -207,6 +207,7 @@ you want to change that to redirect instead, you can set the .. code-block:: xml + @@ -215,9 +216,9 @@ you want to change that to redirect instead, you can set the // app/config/config.php $container->loadFromExtension( - 'cmf_seo' => array( + 'cmf_seo' => [ 'original_route_pattern' => 'redirect', - ), + ], ); .. _bundles-seo-title-description-template: @@ -256,6 +257,7 @@ For instance, to configure the titles of the symfony.com pages, you would do: .. code-block:: xml + @@ -263,9 +265,9 @@ For instance, to configure the titles of the symfony.com pages, you would do: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( + $container->loadFromExtension('cmf_seo', [ 'title' => '%%content_title%% - Symfony', - )); + ]); .. caution:: @@ -292,6 +294,7 @@ For instance, you can do: .. code-block:: xml + loadFromExtension('cmf_seo', array( + $container->loadFromExtension('cmf_seo', [ 'title' => 'seo.title', 'description' => 'seo.description', - )); + ]); And then configure the translation messages: @@ -331,12 +334,12 @@ And then configure the translation messages: .. code-block:: php // app/Resources/translations/messages.en.php - return array( - 'seo' => array( + return [ + 'seo' => [ 'title' => '%content_title% | Default title', 'description' => 'Default description. %content_description', - ), - ); + ], + ]; .. code-block:: yaml @@ -359,14 +362,15 @@ For changing the default translation domain (messages), you should use the # app/config/config.yml cmf_seo: - translation_domain: AcmeDemoBundle + translation_domain: seo .. code-block:: xml + @@ -374,9 +378,9 @@ For changing the default translation domain (messages), you should use the // app/config/config.php $container->loadFromExtension( - 'cmf_seo' => array( - 'translation_domain' => 'AcmeDemoBundle', - ), + 'cmf_seo' => [ + 'translation_domain' => 'seo', + ], ); .. _bundles-seo-alternate-locale: diff --git a/bundles/seo/seo_aware.rst b/bundles/seo/seo_aware.rst index 866e22a2..7f9d30b2 100644 --- a/bundles/seo/seo_aware.rst +++ b/bundles/seo/seo_aware.rst @@ -9,8 +9,8 @@ In order to save the ``SeoMetadata`` in the object, the object should implement the ``SeoAwareInterface``. This requires a getter and a setter for the ``SeoMetadata``:: - // src/Acme/SiteBundle/Document/Page.php - namespace Acme\SiteBundle\Document; + // src/AppBundle/Document/Page.php + namespace AppBundle\Document; use Symfony\Cmf\Bundle\SeoBundle\SeoAwareInterface; @@ -37,7 +37,7 @@ the ``SeoMetadata``:: Now you can set some SEO data for this ``Page`` using the metadata:: - use Acme\SiteBundle\Document\Page; + use AppBundle\Document\Page; use Symfony\Cmf\Bundle\SeoBundle\SeoMetadata; $page = new Page(); @@ -79,11 +79,11 @@ To be able to use this document, you have to enable the PHPCR persistence: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'persistence' => array( + $container->loadFromExtension('cmf_seo', [ + 'persistence' => [ 'phpcr' => true, - ), - )); + ], + ]); .. tip:: @@ -97,8 +97,8 @@ After you've enabled PHPCR, map ``$seoMetadata`` as a child: .. code-block:: php-annotations - // src/Acme/SiteBundle/Document/Page.php - namespace Acme\SiteBundle\Document; + // src/AppBundle/Document/Page.php + namespace AppBundle\Document; use Symfony\Cmf\Bundle\SeoBundle\SeoAwareInterface; use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; @@ -118,8 +118,8 @@ After you've enabled PHPCR, map ``$seoMetadata`` as a child: .. code-block:: yaml - # src/Acme/SiteBundle/Resources/config/doctrine/Page.odm.yml - Acme\SiteBundle\Document\Page: + # src/AppBundle/Resources/config/doctrine/Page.odm.yml + AppBundle\Document\Page: # ... child: # ... @@ -127,15 +127,15 @@ After you've enabled PHPCR, map ``$seoMetadata`` as a child: .. code-block:: xml - - + + - + @@ -144,10 +144,10 @@ After you've enabled PHPCR, map ``$seoMetadata`` as a child: And after that, you can use the ``Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata`` document:: - // src/Acme/SiteBundle/DataFixture/PHPCR/LoadPageData.php - namespace Acme\SiteBundle\DataFixtures\PHPCR; + // src/AppBundle/DataFixture/PHPCR/LoadPageData.php + namespace AppBundle\DataFixtures\PHPCR; - use Acme\SiteBundle\Document\Page; + use AppBundle\Document\Page; use Symfony\Cmf\Bundle\SeoBundle\Doctrine\Phpcr\SeoMetadata; use Doctrine\Common\Persistence\ObjectManager; use Doctrine\Common\DataFixtures\FixtureInterface; @@ -186,8 +186,8 @@ object: .. code-block:: php-annotations - // src/Acme/SiteBundle/Entity/Page.php - namespace Acme\SiteBundle\Entity; + // src/AppBundle/Entity/Page.php + namespace AppBundle\Entity; use Symfony\Cmf\Bundle\SeoBundle\SeoAwareInterface; use Doctrine\ORM\Mapping as ORM; @@ -207,8 +207,8 @@ object: .. code-block:: yaml - # src/Acme/SiteBundle/Resources/config/doctrine/Page.orm.yml - Acme\SiteBundle\Entity\Page: + # src/AppBundle/Resources/config/doctrine/Page.orm.yml + AppBundle\Entity\Page: # ... fields: # ... @@ -217,14 +217,14 @@ object: .. code-block:: xml - + - + diff --git a/bundles/seo/sitemap.rst b/bundles/seo/sitemap.rst index 200a2dc4..13edd259 100644 --- a/bundles/seo/sitemap.rst +++ b/bundles/seo/sitemap.rst @@ -77,11 +77,11 @@ settings: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'sitemap' => array( + $container->loadFromExtension('cmf_seo', [ + 'sitemap' => [ 'enabled' => true, - ), - )); + ], + ]); Rendering Sitemaps ------------------ @@ -107,7 +107,7 @@ The templates are specified for a specific sitemap (see below) or in the sitemap: defaults: templates: - html: AppBundle:Sitemap:default.html.twig + html: sitemap/default.html.twig .. code-block:: xml @@ -118,7 +118,7 @@ The templates are specified for a specific sitemap (see below) or in the - + @@ -127,15 +127,15 @@ The templates are specified for a specific sitemap (see below) or in the .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'sitemap' => array( - 'defaults' => array( - 'templates' => array( - 'html' => 'AppBundle:Sitemap:default.html.twig', - ), - ), - ), - )); + $container->loadFromExtension('cmf_seo', [ + 'sitemap' => [ + 'defaults' => [ + 'templates' => [ + 'html' => 'sitemap/default.html.twig', + ], + ], + ], + ]); The formats for the templates are not limited, you can add any format you like. @@ -200,21 +200,23 @@ The service definition looks as follows: .. code-block:: yaml + # app/config/services.yml services: - seo.sitemap.guesser.last_modified: + app.seo.sitemap.guesser.last_modified: class: AppBundle\Seo\Sitemap\LastModifiedGuesser tags: - { name: cmf_seo.sitemap.guesser, priority: 10 } .. code-block:: xml - + + - + @@ -222,8 +224,11 @@ The service definition looks as follows: .. code-block:: php - $container->register('seo.sitemap.guesser.last_modified', 'AppBundle\Seo\Sitemap\LastModifiedGuesser') - ->addTag('cmf_seo.sitemap.guesser', array('priority' => 10) + // app/config/config.php + use AppBundle\Seo\Sitemap\LastModifiedGuesser; + + $container->register('app.seo.sitemap.guesser.last_modified', LastModifiedGuesser::class) + ->addTag('cmf_seo.sitemap.guesser', [priority' => 10] ; Loaders and voters work exactly the same, with the tags ``cmf_seo.sitemap.loader`` @@ -253,7 +258,7 @@ sitemaps, you need to explicitly specify ``sitemap`` as well: categories: default_change_frequency: hourly templates: - html: AppBundle:Sitemap:categories.html.twig + html: sitemap/categories.html.twig .. code-block:: xml @@ -265,7 +270,7 @@ sitemaps, you need to explicitly specify ``sitemap`` as well: - + @@ -274,19 +279,19 @@ sitemaps, you need to explicitly specify ``sitemap`` as well: .. code-block:: php // app/config/config.php - $container->loadFromExtension('cmf_seo', array( - 'sitemap' => array( - 'configurations' => array( + $container->loadFromExtension('cmf_seo', [ + 'sitemap' => [ + 'configurations' => [ 'sitemap' => null, - 'categories' => array( + 'categories' => [ 'default_change_frequency' => 'hourly', - 'templates' => array( - 'html' => 'AppBundle:Sitemap:categories.html.twig', - ), - ), - ), - ), - )); + 'templates' => [ + 'html' => 'sitemap/categories.html.twig', + ], + ], + ], + ], + ]); You will now be able to serve a categories sitemap at ``/categories.html``. diff --git a/bundles/seo/twig.rst b/bundles/seo/twig.rst index c0e3a1c9..415354d3 100644 --- a/bundles/seo/twig.rst +++ b/bundles/seo/twig.rst @@ -31,7 +31,7 @@ base twig template and override it in a sub template, calling - + {% extends 'base.html.twig' %} {% block metadata %}