Initial commit: apps.supersam24.ru

vendor/cakephp/bake/docs/en/development.rst

@@ -0,0 +1,304 @@
+Extending Bake
+##############
+
+Bake features an extensible architecture that allows your application or plugins
+to modify or add-to the base functionality. Bake makes use of a dedicated
+view class which uses the `Twig <https://twig.symfony.com/>`_ template engine.
+
+Bake Events
+===========
+
+As a view class, ``BakeView`` emits the same events as any other view class,
+plus one extra initialize event. However, whereas standard view classes use the
+event prefix "View.", ``BakeView`` uses the event prefix "Bake.".
+
+The initialize event can be used to make changes which apply to all baked
+output, for example to add another helper to the bake view class this event can
+be used::
+
+    <?php
+    // config/bootstrap_cli.php
+
+    use Cake\Event\Event;
+    use Cake\Event\EventManager;
+
+    EventManager::instance()->on('Bake.initialize', function (Event $event) {
+        $view = $event->getSubject();
+
+        // In my bake templates, allow the use of the MySpecial helper
+        $view->loadHelper('MySpecial', ['some' => 'config']);
+
+        // And add an $author variable so it's always available
+        $view->set('author', 'Andy');
+
+    });
+
+If you want to modify bake from within another plugin, putting your plugin's
+bake events in the plugin ``config/bootstrap.php`` file is a good idea.
+
+Bake events can be handy for making small changes to existing templates.
+For example, to change the variable names used when baking controller/template
+files one can use a function listening for ``Bake.beforeRender`` to modify the
+variables used in the bake templates::
+
+    <?php
+    // config/bootstrap_cli.php
+
+    use Cake\Event\Event;
+    use Cake\Event\EventManager;
+
+    EventManager::instance()->on('Bake.beforeRender', function (Event $event) {
+        $view = $event->getSubject();
+
+        // Use $rows for the main data variable in indexes
+        if ($view->get('pluralName')) {
+            $view->set('pluralName', 'rows');
+        }
+        if ($view->get('pluralVar')) {
+            $view->set('pluralVar', 'rows');
+        }
+
+        // Use $theOne for the main data variable in view/edit
+        if ($view->get('singularName')) {
+            $view->set('singularName', 'theOne');
+        }
+        if ($view->get('singularVar')) {
+            $view->set('singularVar', 'theOne');
+        }
+
+    });
+
+You may also scope the ``Bake.beforeRender`` and ``Bake.afterRender`` events to
+a specific generated file. For instance, if you want to add specific actions to
+your UsersController when generating from a **Controller/controller.twig** file,
+you can use the following event::
+
+    <?php
+    // config/bootstrap_cli.php
+
+    use Cake\Event\Event;
+    use Cake\Event\EventManager;
+    use Cake\Utility\Hash;
+
+    EventManager::instance()->on(
+        'Bake.beforeRender.Controller.controller',
+        function (Event $event) {
+            $view = $event->getSubject();
+            if ($view->viewVars['name'] == 'Users') {
+                // add the login and logout actions to the Users controller
+                $view->set('actions', [
+                    'login',
+                    'logout',
+                    'index',
+                    'view',
+                    'add',
+                    'edit',
+                    'delete'
+                ]);
+            }
+        }
+    );
+
+By scoping event listeners to specific bake templates, you can simplify your
+bake related event logic and provide callbacks that are easier to test.
+
+Bake Template Syntax
+====================
+
+Bake template files use the `Twig <https://twig.symfony.com/doc/2.x/>`__ template syntax.
+
+One way to see/understand how bake templates works, especially when attempting
+to modify bake template files, is to bake a class and compare the template used
+with the pre-processed template file which is left in the application's
+**tmp/bake** folder.
+
+So, for example, when baking a shell like so:
+
+.. code-block:: bash
+
+    bin/cake bake shell Foo
+
+The template used (**vendor/cakephp/bake/src/Template/Bake/Shell/shell.twig**)
+looks like this::
+
+    <?php
+    namespace {{ namespace }}\Shell;
+
+    use Cake\Console\Shell;
+
+    /**
+     * {{ name }} shell command.
+     */
+    class {{ name }}Shell extends Shell
+    {
+        /**
+         * main() method.
+         *
+         * @return bool|int Success or error code.
+         */
+        public function main()
+        {
+        }
+
+    }
+
+And the resultant baked class (**src/Shell/FooShell.php**) looks like this::
+
+    <?php
+    namespace App\Shell;
+
+    use Cake\Console\Shell;
+
+    /**
+     * Foo shell command.
+     */
+    class FooShell extends Shell
+    {
+        /**
+         * main() method.
+         *
+         * @return bool|int Success or error code.
+         */
+        public function main()
+        {
+        }
+
+    }
+
+.. note::
+
+    Prior to version 1.5.0 bake used a custom erb-style tags inside .ctp template files.
+
+    * ``<%`` A Bake template php open tag
+    * ``%>`` A Bake template php close tag
+    * ``<%=`` A Bake template php short-echo tag
+    * ``<%-`` A Bake template php open tag, stripping any leading whitespace
+      before the tag
+    * ``-%>`` A Bake template php close tag, stripping trailing whitespace after
+      the tag
+
+.. _creating-a-bake-theme:
+
+Creating a Bake Theme
+=====================
+
+If you wish to modify the output produced by the "bake" command, you can
+create your own bake 'theme' which allows you to replace some or all of the
+templates that bake uses. The best way to do this is:
+
+#. Bake a new plugin. The name of the plugin is the bake 'theme' name
+#. Create a new directory **plugins/[name]/src/Template/Bake/Template/**.
+#. Copy any templates you want to override from
+   **vendor/cakephp/bake/src/Template/Bake/Template** to matching files in your
+   plugin.
+#. When running bake use the ``--theme`` option to specify the bake-theme you
+   want to use. To avoid having to specify this option in each call, you can also
+   set your custom theme to be used as default theme::
+
+        <?php
+        // in config/bootstrap.php or config/bootstrap_cli.php
+        Configure::write('Bake.theme', 'MyTheme');
+
+Customizing the Bake Templates
+==============================
+
+If you wish to modify the default output produced by the "bake" command, you can
+create your own bake templates in your application. This way does not use the
+``--theme`` option in the command line when baking. The best way to do this is:
+
+#. Create a new directory **/src/Template/Bake/**.
+#. Copy any templates you want to override from
+   **vendor/cakephp/bake/src/Template/Bake/** to matching files in your
+   application.
+
+Creating New Bake Command Options
+=================================
+
+It's possible to add new bake command options, or override the ones provided by
+CakePHP by creating tasks in your application or plugins. By extending
+``Bake\Shell\Task\BakeTask``, bake will find your new task and include it as
+part of bake.
+
+As an example, we'll make a task that creates an arbitrary foo class. First,
+create the task file **src/Shell/Task/FooTask.php**. We'll extend the
+``SimpleBakeTask`` for now as our shell task will be simple. ``SimpleBakeTask``
+is abstract and requires us to define 3 methods that tell bake what the task is
+called, where the files it generates should go, and what template to use. Our
+FooTask.php file should look like::
+
+    <?php
+    namespace App\Shell\Task;
+
+    use Bake\Shell\Task\SimpleBakeTask;
+
+    class FooTask extends SimpleBakeTask
+    {
+        public $pathFragment = 'Foo/';
+
+        public function name()
+        {
+            return 'foo';
+        }
+
+        public function fileName($name)
+        {
+            return $name . 'Foo.php';
+        }
+
+        public function template()
+        {
+            return 'foo';
+        }
+
+    }
+
+Once this file has been created, we need to create a template that bake can use
+when generating code. Create **src/Template/Bake/foo.twig**. In this file we'll
+add the following content::
+
+    <?php
+    namespace {{ namespace }}\Foo;
+
+    /**
+     * {{ name }} foo
+     */
+    class {{ name }}Foo
+    {
+        // Add code.
+    }
+
+You should now see your new task in the output of ``bin/cake bake``. You can
+run your new task by running ``bin/cake bake foo Example``.
+This will generate a new ``ExampleFoo`` class in **src/Foo/ExampleFoo.php**
+for your application to use.
+
+If you want the ``bake`` call to also create a test file for your
+``ExampleFoo`` class, you need to overwrite the ``bakeTest()`` method in the
+``FooTask`` class to register the class suffix and namespace for your custom
+command name::
+
+    public function bakeTest($className)
+    {
+        if (!isset($this->Test->classSuffixes[$this->name()])) {
+          $this->Test->classSuffixes[$this->name()] = 'Foo';
+        }
+
+        $name = ucfirst($this->name());
+        if (!isset($this->Test->classTypes[$name])) {
+          $this->Test->classTypes[$name] = 'Foo';
+        }
+
+        return parent::bakeTest($className);
+    }
+
+* The **class suffix** will be appened to the name provided in your ``bake``
+  call. In the previous example, it would create a ``ExampleFooTest.php`` file.
+* The **class type** will be the sub-namespace used that will lead to your
+  file (relative to the app or the plugin you are baking into). In the previous
+  example, it would create your test with the namespace ``App\Test\TestCase\Foo``
+  .
+
+.. meta::
+    :title lang=en: Extending Bake
+    :keywords lang=en: command line interface,development,bake view, bake template syntax,twig,erb tags,percent tags
+