Permalink
Browse files

init new repository

  • Loading branch information...
0 parents commit 49eece5ce4dfab9c0aa72bebe3438c7991818520 @gregquat gregquat committed May 24, 2011
Showing with 28,302 additions and 0 deletions.
  1. +265 −0 book/bundles.rst
  2. +717 −0 book/controller.rst
  3. +183 −0 book/doctrine/dbal.rst
  4. +11 −0 book/doctrine/index.rst
  5. +234 −0 book/doctrine/model.rst
  6. +787 −0 book/doctrine/orm.rst
  7. +1,168 −0 book/forms.rst
  8. +746 −0 book/from_flat_php_to_symfony2.rst
  9. +1,041 −0 book/http_cache.rst
  10. +516 −0 book/http_fundamentals.rst
  11. BIN book/images/forms-simple.png
  12. +25 −0 book/index.rst
  13. +463 −0 book/internals/event_dispatcher.rst
  14. +10 −0 book/internals/index.rst
  15. +304 −0 book/internals/kernel.rst
  16. +70 −0 book/internals/overview.rst
  17. +285 −0 book/internals/profiler.rst
  18. +34 −0 book/map.rst.inc
  19. +939 −0 book/page_creation.rst
  20. +1,160 −0 book/routing.rst
  21. +1,635 −0 book/security.rst
  22. +1,012 −0 book/service_container.rst
  23. +39 −0 book/stable_api.rst
  24. +1,150 −0 book/templating.rst
  25. +757 −0 book/testing.rst
  26. +823 −0 book/translation.rst
  27. +602 −0 book/validation.rst
  28. +37 −0 contributing/code/bugs.rst
  29. +78 −0 contributing/code/conventions.rst
  30. +13 −0 contributing/code/index.rst
  31. +37 −0 contributing/code/license.rst
  32. +155 −0 contributing/code/patches.rst
  33. +21 −0 contributing/code/security.rst
  34. +76 −0 contributing/code/standards.rst
  35. +85 −0 contributing/code/tests.rst
  36. +8 −0 contributing/community/index.rst
  37. +60 −0 contributing/community/irc.rst
  38. +15 −0 contributing/community/other.rst
  39. +161 −0 contributing/documentation/format.rst
  40. +10 −0 contributing/documentation/index.rst
  41. +50 −0 contributing/documentation/license.rst
  42. +67 −0 contributing/documentation/overview.rst
  43. +84 −0 contributing/documentation/translations.rst
  44. +11 −0 contributing/index.rst
  45. +21 −0 contributing/map.rst.inc
  46. +138 −0 cookbook/assetic/yuicompressor.rst
  47. +221 −0 cookbook/bundles/extension.rst
  48. +92 −0 cookbook/cache/varnish.rst
  49. +351 −0 cookbook/configuration/environments.rst
  50. +162 −0 cookbook/configuration/external_parameters.rst
  51. +88 −0 cookbook/configuration/pdo_session_storage.rst
  52. +261 −0 cookbook/console.rst
  53. +88 −0 cookbook/controller/error_pages.rst
  54. +46 −0 cookbook/controller/service.rst
  55. +60 −0 cookbook/debugging.rst
  56. +279 −0 cookbook/doctrine/doctrine_fixtures.rst
  57. +168 −0 cookbook/doctrine/migrations.rst
  58. +513 −0 cookbook/doctrine/mongodb.rst
  59. +173 −0 cookbook/doctrine/reverse_engineering.rst
  60. +132 −0 cookbook/email.rst
  61. +130 −0 cookbook/event_dispatcher/class_extension.rst
  62. +56 −0 cookbook/event_dispatcher/method_behavior.rst
  63. +5 −0 cookbook/form/create_custom_field_type.rst
  64. +5 −0 cookbook/form/file_uploads.rst
  65. +560 −0 cookbook/form/twig_form_customization.rst
  66. +57 −0 cookbook/gmail.rst
  67. +51 −0 cookbook/index.rst
  68. +215 −0 cookbook/logging/monolog.rst
  69. +43 −0 cookbook/map.rst.inc
  70. +170 −0 cookbook/profiler/data_collector.rst
  71. +89 −0 cookbook/request/mime_type.rst
  72. +76 −0 cookbook/routing/scheme.rst
  73. +198 −0 cookbook/security/acl.rst
  74. +184 −0 cookbook/security/acl_advanced.rst
  75. +11 −0 cookbook/security/custom_provider.rst
  76. +10 −0 cookbook/security/entity_provider.rst
  77. +11 −0 cookbook/security/force_https.rst
  78. +74 −0 cookbook/security/form_login.rst
  79. +14 −0 cookbook/security/remember_me.rst
  80. +11 −0 cookbook/security/securing_services.rst
  81. +187 −0 cookbook/security/voters.rst
  82. +212 −0 cookbook/service_container/factories.rst
  83. +542 −0 cookbook/service_container/parentservices.rst
  84. +254 −0 cookbook/symfony1.rst
  85. +298 −0 cookbook/templating/PHP.rst
  86. +20 −0 cookbook/testing/http_authentication.rst
  87. +41 −0 cookbook/testing/insulating_clients.rst
  88. +62 −0 cookbook/testing/profiling.rst
  89. +101 −0 cookbook/tools/autoloader.rst
  90. +207 −0 cookbook/tools/finder.rst
  91. +97 −0 cookbook/validation/custom_constraint.rst
  92. +125 −0 glossary.rst
  93. BIN images/book/security_admin_role_access.png
  94. BIN images/book/security_anonymous_user_access.png
  95. BIN images/book/security_anonymous_user_denied_authorization.png
  96. BIN images/book/security_authentication_authorization.png
  97. BIN images/book/security_full_step_authorization.png
  98. BIN images/book/security_ryan_no_role_admin_access.png
  99. BIN images/docs-pull-request.png
  100. BIN images/http-xkcd-request.png
  101. BIN images/http-xkcd.png
  102. BIN images/quick_tour/welcome.jpg
  103. BIN images/request-flow.png
  104. +63 −0 index.rst
  105. +10 −0 quick_tour/index.rst
  106. +328 −0 quick_tour/the_architecture.rst
  107. +380 −0 quick_tour/the_big_picture.rst
  108. +269 −0 quick_tour/the_controller.rst
  109. +283 −0 quick_tour/the_view.rst
  110. +385 −0 reference/YAML.rst
  111. +120 −0 reference/configuration/doctrine.rst
  112. +70 −0 reference/configuration/monolog.rst
  113. +141 −0 reference/configuration/security.rst
  114. +73 −0 reference/configuration/twig.rst
  115. +58 −0 reference/constraints.rst
  116. +40 −0 reference/constraints/Callback.rst
  117. +232 −0 reference/constraints/Choice.rst
  118. +135 −0 reference/constraints/Collection.rst
  119. +15 −0 reference/constraints/Date.rst
  120. +15 −0 reference/constraints/DateTime.rst
  121. +16 −0 reference/constraints/Email.rst
  122. +17 −0 reference/constraints/False.rst
  123. +96 −0 reference/constraints/File.rst
  124. +16 −0 reference/constraints/Max.rst
  125. +63 −0 reference/constraints/MaxLength.rst
  126. +16 −0 reference/constraints/Min.rst
  127. +63 −0 reference/constraints/MinLength.rst
  128. +16 −0 reference/constraints/NotBlank.rst
  129. +15 −0 reference/constraints/NotNull.rst
  130. +18 −0 reference/constraints/Regex.rst
  131. +15 −0 reference/constraints/Time.rst
  132. +106 −0 reference/constraints/True.rst
  133. +33 −0 reference/constraints/Type.rst
  134. +17 −0 reference/constraints/Url.rst
  135. +219 −0 reference/constraints/Valid.rst
  136. +198 −0 reference/dic_tags.rst
  137. +87 −0 reference/forms/twig_reference.rst
  138. +50 −0 reference/forms/types.rst
  139. +63 −0 reference/forms/types/birthday.rst
  140. +54 −0 reference/forms/types/checkbox.rst
  141. +146 −0 reference/forms/types/choice.rst
  142. +7 −0 reference/forms/types/collection.rst
  143. +59 −0 reference/forms/types/country.rst
  144. +43 −0 reference/forms/types/csrf.rst
  145. +89 −0 reference/forms/types/date.rst
  146. +68 −0 reference/forms/types/datetime.rst
  147. +40 −0 reference/forms/types/email.rst
  148. +63 −0 reference/forms/types/entity.rst
  149. +20 −0 reference/forms/types/field.rst
  150. +7 −0 reference/forms/types/file.rst
  151. +7 −0 reference/forms/types/form.rst
  152. +24 −0 reference/forms/types/hidden.rst
  153. +58 −0 reference/forms/types/integer.rst
  154. +60 −0 reference/forms/types/language.rst
  155. +61 −0 reference/forms/types/locale.rst
  156. +56 −0 reference/forms/types/map.rst.inc
  157. +76 −0 reference/forms/types/money.rst
  158. +72 −0 reference/forms/types/number.rst
  159. +17 −0 reference/forms/types/options/data.rst.inc
  160. +6 −0 reference/forms/types/options/data_timezone.rst.inc
  161. +4 −0 reference/forms/types/options/date_format.rst.inc
  162. +8 −0 reference/forms/types/options/date_input.rst.inc
  163. +10 −0 reference/forms/types/options/date_pattern.rst.inc
  164. +11 −0 reference/forms/types/options/date_widget.rst.inc
  165. +6 −0 reference/forms/types/options/days.rst.inc
  166. +18 −0 reference/forms/types/options/disabled.rst.inc
  167. +4 −0 reference/forms/types/options/error_bubbling.rst.inc
  168. +3 −0 reference/forms/types/options/expanded.rst.inc
  169. +2 −0 reference/forms/types/options/hours.rst.inc
  170. +8 −0 reference/forms/types/options/label.rst.inc
  171. +3 −0 reference/forms/types/options/max_length.rst.inc
  172. +2 −0 reference/forms/types/options/minutes.rst.inc
  173. +2 −0 reference/forms/types/options/months.rst.inc
  174. +5 −0 reference/forms/types/options/multiple.rst.inc
  175. +28 −0 reference/forms/types/options/preferred_choices.rst.inc
  176. +7 −0 reference/forms/types/options/property_path.rst.inc
  177. +3 −0 reference/forms/types/options/read_only.rst.inc
  178. +10 −0 reference/forms/types/options/required.rst.inc
  179. +2 −0 reference/forms/types/options/seconds.rst.inc
  180. +5 −0 reference/forms/types/options/trim.rst.inc
  181. +6 −0 reference/forms/types/options/user_timezone.rst.inc
  182. +2 −0 reference/forms/types/options/with_seconds.rst.inc
  183. +3 −0 reference/forms/types/options/years.rst.inc
  184. +52 −0 reference/forms/types/password.rst
  185. +59 −0 reference/forms/types/percent.rst
  186. +48 −0 reference/forms/types/radio.rst
  187. +7 −0 reference/forms/types/repeated.rst
  188. +42 −0 reference/forms/types/search.rst
  189. +43 −0 reference/forms/types/text.rst
  190. +43 −0 reference/forms/types/textarea.rst
  191. +90 −0 reference/forms/types/time.rst
  192. +55 −0 reference/forms/types/timezone.rst
  193. +46 −0 reference/forms/types/url.rst
  194. +17 −0 reference/index.rst
  195. +21 −0 reference/map.rst.inc
@@ -0,0 +1,265 @@
+.. index::
+ single: Bundles; Best Practices
+
+Bundles
+=======
+
+A bundle is a directory that has a well-defined structure and can host anything
+from classes to controllers and web resources. Even if bundles are very
+flexible, you should follow some best practices if you want to distribute them.
+
+.. index::
+ pair: Bundles; Naming Conventions
+
+.. _bundles-naming-conventions:
+
+Bundle Name
+-----------
+
+A bundle is also a PHP namespace. The namespace must follow the technical
+interoperability `standards`_ for PHP 5.3 namespaces and class names: it
+starts with a vendor segment, followed by zero or more category segments, and
+it ends with the namespace short name, which must end with a ``Bundle``
+suffix.
+
+A namespace becomes a bundle as soon as you add a bundle class to it. The
+bundle class name must follow these simple rules:
+
+* Use only alphanumeric characters and underscores;
+* Use a CamelCased name;
+* Use a descriptive and short name (no more than 2 words);
+* Prefix the name with the concatenation of the vendor (and optionally the
+ category namespaces);
+* Suffix the name with ``Bundle``.
+
+Here are some valid bundle namespaces and class names:
+
++-----------------------------------+--------------------------+
+| Namespace | Bundle Class Name |
++===================================+==========================+
+| ``Acme\Bundle\BlogBundle`` | ``AcmeBlogBundle`` |
++-----------------------------------+--------------------------+
+| ``Acme\Bundle\Social\BlogBundle`` | ``AcmeSocialBlogBundle`` |
++-----------------------------------+--------------------------+
+| ``Acme\BlogBundle`` | ``AcmeBlogBundle`` |
++-----------------------------------+--------------------------+
+
+By convention, the ``getName()`` method of the bundle class should return the
+class name.
+
+.. note::
+
+ If you share your bundle publicly, you must use the bundle class name as
+ the name of the repository (``AcmeBlogBundle`` and not ``BlogBundle``
+ for instance).
+
+.. note::
+
+ Symfony2 core Bundles do not prefix the Bundle class with ``Symfony``
+ and always add a ``Bundle`` subnamespace; for example:
+ :class:`Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle`.
+
+Directory Structure
+-------------------
+
+The basic directory structure of a ``HelloBundle`` bundle must read as
+follows:
+
+.. code-block:: text
+
+ XXX/...
+ HelloBundle/
+ HelloBundle.php
+ Controller/
+ Resources/
+ meta/
+ LICENSE
+ config/
+ doc/
+ index.rst
+ translations/
+ views/
+ public/
+ Tests/
+
+The ``XXX`` directory(ies) reflects the namespace structure of the bundle.
+
+The following files are mandatory:
+
+* ``HelloBundle.php``;
+* ``Resources/meta/LICENSE``: The full license for the code;
+* ``Resources/doc/index.rst``: The root file for the Bundle documentation.
+
+.. note::
+
+ These conventions ensure that automated tools can rely on this default
+ structure to work.
+
+The depth of sub-directories should be kept to the minimal for most used
+classes and files (2 levels at a maximum). More levels can be defined for
+non-strategic, less-used files.
+
+The bundle directory is read-only. If you need to write temporary files, store
+them under the ``cache/`` or ``log/`` directory of the host application. Tools
+can generate files in the bundle directory structure, but only if the generated
+files are going to be part of the repository.
+
+The following classes and files have specific emplacements:
+
++---------------------------+-----------------------------+
+| Type | Directory |
++===========================+=============================+
+| Controllers | ``Controller/`` |
++---------------------------+-----------------------------+
+| Translation files | ``Resources/translations/`` |
++---------------------------+-----------------------------+
+| Templates | ``Resources/views/`` |
++---------------------------+-----------------------------+
+| Unit and Functional Tests | ``Tests/`` |
++---------------------------+-----------------------------+
+| Web Resources | ``Resources/public/`` |
++---------------------------+-----------------------------+
+| Configuration | ``Resources/config/`` |
++---------------------------+-----------------------------+
+| Commands | ``Command/`` |
++---------------------------+-----------------------------+
+
+Classes
+-------
+
+The bundle directory structure is used as the namespace hierarchy. For
+instance, a ``HelloController`` controller is stored in
+``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
+class name is ``Bundle\HelloBundle\Controller\HelloController``.
+
+All classes and files must follow the Symfony2 coding :doc:`standards
+</contributing/code/standards>`.
+
+Some classes should be seen as facades and should be as short as possible, like
+Commands, Helpers, Listeners, and Controllers.
+
+Classes that connects to the Event Dispatcher should be suffixed with
+``Listener``.
+
+Exceptions classes should be stored in an ``Exception`` sub-namespace.
+
+Vendors
+-------
+
+A bundle must not embed third-party PHP libraries. It should rely on the
+standard Symfony2 autoloading instead.
+
+A bundle should not embed third-party libraries written in JavaScript, CSS, or
+any other language.
+
+Tests
+-----
+
+A bundle should come with a test suite written with PHPUnit and stored under
+the ``Tests/`` directory. Tests should follow the following principles:
+
+* The test suite must be executable with a simple ``phpunit`` command run from
+ a sample application;
+* The functional tests should only be used to test the response output and
+ some profiling information if you have some;
+* The code coverage should at least covers 95% of the code base.
+
+.. note::
+ A test suite must not contain ``AllTests.php`` scripts, but must rely on the
+ existence of a ``phpunit.xml.dist`` file.
+
+Documentation
+-------------
+
+All classes and functions must come with full PHPDoc.
+
+Extensive documentation should also be provided in the :doc:`reStructuredText
+</contributing/documentation/format>` format, under the ``Resources/doc/``
+directory; the ``Resources/doc/index.rst`` file is the only mandatory file.
+
+Controllers
+-----------
+
+As a best practice, controllers in a bundle that's meant to be distributed
+to others must not extend the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` base class.
+They can implement
+:class:`Symfony\\Component\\DependencyInjection\\ContainerAwareInterface` or
+extend :class:`Symfony\\Component\\DependencyInjection\\ContainerAware`
+instead.
+
+.. note::
+
+ If you have a look at
+ :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` methods,
+ you will see that they are only nice shortcuts to ease the learning curve.
+
+Templates
+---------
+
+If a bundle provides templates, they must use Twig. A bundle must not provide
+a main layout, except if it provides a full working application.
+
+Translation Files
+-----------------
+
+If a bundle provides message translations, they must be defined in the XLIFF
+format; the domain should be named after the bundle name (``bundle.hello``).
+
+A bundle must not override existing messages from another bundle.
+
+Configuration
+-------------
+
+To provide more flexibility, a bundle can provide configurable settings by
+using the Symfony2 built-in mechanisms.
+
+For simple configuration settings, rely on the default ``parameters`` entry of
+the Symfony2 configuration. Symfony2 parameters are simple key/value pairs; a
+value being any valid PHP value. Each parameter name should start with a
+lower-cased short version of the bundle name using underscores (``acme_hello``
+for ``AcmeHelloBundle``, or ``acme_social_blog`` for ``Acme\Social\BlogBundle``
+for instance), though this is just a best-practice suggestion. The rest of
+the parameter name will use a period (``.``) to separate different parts
+(e.g. ``acme_hello.email.from``).
+
+The end user can provide values in any configuration file:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ parameters:
+ acme_hello.email.from: fabien@example.com
+
+ .. code-block:: xml
+
+ <!-- app/config/config.xml -->
+ <parameters>
+ <parameter key="acme_hello.email.from">fabien@example.com</parameter>
+ </parameters>
+
+ .. code-block:: php
+
+ // app/config/config.php
+ $container->setParameter('acme_hello.email.from', 'fabien@example.com');
+
+ .. code-block:: ini
+
+ [parameters]
+ acme_hello.email.from = fabien@example.com
+
+Retrieve the configuration parameters in your code from the container::
+
+ $container->getParameter('acme_hello.email.from');
+
+Even if this mechanism is simple enough, you are highly encouraged to use the
+semantic configuration described in the cookbook.
+
+Learn more from the Cookbook
+----------------------------
+
+* :doc:`/cookbook/bundles/extension`
+
+.. _standards: http://groups.google.com/group/php-standards/web/psr-0-final-proposal
Oops, something went wrong. Retry.

0 comments on commit 49eece5

Please sign in to comment.