Differences

This shows you the differences between two versions of the page.

--- development:code_generators [2018/10/24 15:26] – demiankatz
+++ development:code_generators [2023/11/09 21:19] (current) – [extendservice] demiankatz
@@ Line 1: / Line 1: @@
 ====== Code Generators ======
-Starting with VuFind 2.4, command line code generation tools are available to help save you time when performing certain common tasks.
+Command line code generation tools are available to help save you time when performing certain common tasks.
 ===== Creating Routes =====
-Adding new entries to the Zend Framework router can involve tedious array creation, so VuFind includes tools for creating certain kinds of routes automatically from the command line.
+Adding new entries to the router configuration can involve tedious array creation, so VuFind® includes tools for creating certain kinds of routes automatically from the command line.
 ==== Static Routes ====
@@ Line 40: / Line 40: @@
 ===== Creating Themes =====
-Starting with VuFind 4.1, a generator is available to create an example theme for you to customize. The generator not only creates a new theme directory with an example configuration, CSS and template, but it also updates your local config.ini to turn on the new theme and make it a selectable option.
+Starting with VuFind® 4.1, a generator is available to create an example theme for you to customize. The generator not only creates a new theme directory with an example configuration, CSS and template, but it also updates your local config.ini to turn on the new theme and make it a selectable option.
 ==== Usage ====
@@ Line 51: / Line 51: @@
 ===== Creating Theme Mix-ins =====
-Starting with VuFind 4.1, a generator is available to create an example [[development:architecture:user_interface#mix-ins|theme mix-in]] for you to customize. The generator creates a new mix-in directory with an example configuration and script; you will need to manually customize this and add it to your theme.config.php's mixins array in order to activate it.
+Starting with VuFind® 4.1, a generator is available to create an example [[development:architecture:user_interface#mix-ins|theme mix-in]] for you to customize. The generator creates a new mix-in directory with an example configuration and script; you will need to manually customize this and add it to your theme.config.php's mixins array in order to activate it.
 ==== Usage ====
@@ Line 59: / Line 59: @@
 </code>
-===== Overriding Existing Plugins and Services (VuFind 4.x and earlier) =====
+===== Overriding Existing Plugins and Services =====
-If you want to extend one of VuFind's built-in plugins or services, you can use the 'extendservice' generator to create a new subclass and automatically configure your local module to use it.
+==== extendclass ====
-:!: Starting with VuFind 5.0, the 'extendclass' generator is usually a more convenient option. See below for details. You can still use 'extendservice' in 5.0 if you wish, but due to changes in service manager configuration, it is less useful than before.
+If you want to extend one of VuFind®'s built-in plugins or services, you can use the 'extendclass' generator to create a new subclass and automatically configure your local module to use it.
-==== Usage ====
+=== Usage ===
 <code bash>
 cd $VUFIND_HOME
-php public/index.php generate extendservice path/to/service MyModule
+php public/index.php generate extendclass [--extendfactory] Fully\\Qualified\\ClassName MyModule
 </code>
-  * path/to/service is a slash-separated path showing where the service is defined in one of VuFind's existing module.config.php files.
+  * --extendfactory is a switch which will cause the existing factory method to be cloned into your local module. If you omit the switch, the existing factory will be used. :!: Using the existing factory only makes sense for factories that dynamically determine the name of the constructed object using the service name; however, a significant number of VuFind® services use this type of factory starting in release 5.0.
+  * Fully\\Qualified\\ClassName is the name of the class you wish to extend/override -- note the need to escape backslashes on the command line.
   * MyModule is the name of your local module where you wish to create a new class.
-==== Notes ====
+=== Notes ===
-:!: Be sure that MyModule already exists and is included in your VUFIND_LOCAL_MODULES environment variable, or the generator may not work correctly. If MyModule does not yet exist, you can re-run VuFind's install.php script to create it.
+:!: Be sure that MyModule already exists and is included in your VUFIND_LOCAL_MODULES environment variable, or the generator may not work correctly. If MyModule does not yet exist, you can re-run VuFind®'s install.php script to create it.
 :!: If things don't work right away after generating code, you may need to clear your local/cache directory to get rid of outdated configurations.
-:!: Don't forget to escape backslashes in service names within the path/to/service parameter. For example, if you wanted to override the export tool, your path would be "service_manager/factories/VuFind\\Export".
+=== Example ===
-==== Example ====
+Suppose you wish to create a custom subclass of VuFind®'s SolrMarc record driver. The command to generate a custom extension of the default class is:
-Suppose you wish to create a custom subclass of VuFind's SolrMarc record driver. You can see in module/VuFind/config/module.config.php that the plugin is defined like this:
-<code php>
-$config = array(
-    'vufind' => array(
-        ...
-        'plugin_managers' => array(
-            ...
-            'recorddriver' => array(
-                ...
-                'factories' => array(
-                    ...
-                    'solrmarc' => 'VuFind\RecordDriver\Factory::getSolrMarc',
-</code>
-The path to this service would be vufind/plugin_managers/recorddriver/factories/solrmarc (following the nested arrays down from the top). So the command to generate a custom extension of the default class is:
 <code bash>
 cd $VUFIND_HOME
-php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc MyModule
+php public/index.php generate extendclass --extendfactory VuFind\\RecordDriver\\SolrMarc MyModule
 </code>
@@ Line 109: / Line 93: @@
 <code>
-Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Saved file: /.../module/MyModule/src/MyModule/RecordDriver/SolrMarc.php
+Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Created backup: /.../module/MyModule/config/module.config.php.1423850855.bak
+Successfully updated /.../module/MyModule/config/module.config.php
 Successfully updated /.../module/MyModule/config/module.config.php
 </code>
-===== Overriding Existing Plugins and Services (VuFind 5.0 and later) =====
+==== extendservice ====
-If you want to extend one of VuFind's built-in plugins or services, you can use the 'extendclass' generator to create a new subclass and automatically configure your local module to use it.
+You can also use the 'extendservice' generator to create a new subclass and automatically configure your local module to use it. It is recommended that you use 'extendclass' instead, because 'extendservice' is a legacy tool that became less useful when 'extendclass' was introduced in release 5.0. However, 'extendservice' remains available as an alternative approach.
-==== Usage ====
+=== Usage ===
 <code bash>
 cd $VUFIND_HOME
-php public/index.php generate extendclass [--extendfactory] Fully\\Qualified\\ClassName MyModule
+php public/index.php generate extendservice path/to/service MyModule
 </code>
-  * --extendfactory is a switch which will cause the existing factory method to be cloned into your local module. If you omit the switch, the existing factory will be used. :!: Using the existing factory only makes sense for factories that dynamically determine the name of the constructed object using the service name; however, a significant number of VuFind services use this type of factory starting in release 5.0.
+  * path/to/service is a slash-separated path showing where the service is defined in one of VuFind®'s existing module.config.php files.
-  * Fully\\Qualified\\ClassName is the name of the class you wish to extend/override -- note the need to escape backslashes on the command line.
   * MyModule is the name of your local module where you wish to create a new class.
-==== Notes ====
+=== Notes ===
-:!: Be sure that MyModule already exists and is included in your VUFIND_LOCAL_MODULES environment variable, or the generator may not work correctly. If MyModule does not yet exist, you can re-run VuFind's install.php script to create it.
+:!: Be sure that MyModule already exists and is included in your VUFIND_LOCAL_MODULES environment variable, or the generator may not work correctly. If MyModule does not yet exist, you can re-run VuFind®'s install.php script to create it.
 :!: If things don't work right away after generating code, you may need to clear your local/cache directory to get rid of outdated configurations.
-==== Example ====
+:!: Don't forget to escape backslashes in service names within the path/to/service parameter. For example, if you wanted to override the export tool, your path would be "service_manager/factories/VuFind\\Export".
-Suppose you wish to create a custom subclass of VuFind's SolrMarc record driver. The command to generate a custom extension of the default class is:
+=== Example ===
+Suppose you wish to create a custom subclass of VuFind®'s SolrMarc record driver. You can see in module/VuFind/config/module.config.php that the plugin is defined like this:
+<code php>
+$config = array(
+    'vufind' => array(
+        ...
+        'plugin_managers' => array(
+            ...
+            'recorddriver' => array(
+                ...
+                'factories' => array(
+                    ...
+                    'solrmarc' => 'VuFind\RecordDriver\Factory::getSolrMarc',
+</code>
+The path to this service would be vufind/plugin_managers/recorddriver/factories/solrmarc (following the nested arrays down from the top). So the command to generate a custom extension of the default class is:
 <code bash>
 cd $VUFIND_HOME
-php public/index.php generate extendclass --extendfactory VuFind\\RecordDriver\\SolrMarc MyModule
+php public/index.php generate extendservice vufind/plugin_managers/recorddriver/factories/solrmarc MyModule
 </code>
@@ Line 148: / Line 149: @@
 <code>
+Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Saved file: /.../module/MyModule/src/MyModule/RecordDriver/SolrMarc.php
-Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Saved file: /.../module/MyModule/src/MyModule/RecordDriver/Factory.php
 Created backup: /.../module/MyModule/config/module.config.php.1423850855.bak
-Successfully updated /.../module/MyModule/config/module.config.php
 Successfully updated /.../module/MyModule/config/module.config.php
 </code>
@@ Line 158: / Line 158: @@
 ===== Creating New Plugins =====
-:!: This feature was introduced in VuFind 5.1.
+:!: This feature was introduced in VuFind® 5.1.
-If you want to create a new [[development:plugins|plugin]] for VuFind, you can use the 'plugin' generator to create a stub class and (if necessary) factory and automatically update the relevant module configuration.
+If you want to create a new [[development:plugins|plugin]] for VuFind®, you can use the 'plugin' generator to create a stub class and (if necessary) factory and automatically update the relevant module configuration.
 ==== Usage ====
@@ Line 169: / Line 169: @@
 </code>
-  * MyModule\\PluginType\\PluginName is the name of the class you wish to create. The generator will use the first part of the class name to determine which module it belongs in (since modules correspond to namespaces); it will use the last part of the class name to name the class being defined; it will use the middle part to identify what type of plugin is being created and to set up configuration accordingly. Obviously, if you specify a class name that does not correspond with a standard VuFind plugin type, the generator will fail.
+  * MyModule\\PluginType\\PluginName is the name of the class you wish to create. The generator will use the first part of the class name to determine which module it belongs in (since modules correspond to namespaces); it will use the last part of the class name to name the class being defined; it will use the middle part to identify what type of plugin is being created and to set up configuration accordingly. Obviously, if you specify a class name that does not correspond with a standard VuFind® plugin type, the generator will fail.
-  * [optional factory name] may be included to specify the name of an existing factory that should be used to construct your plugin. For example, if your class will not have any dependencies, you can use the simple Zend\\ServiceManager\\Factory\\InvokableFactory to construct the object in a simple fashion. If you do not specify a factory name, the generator will create a factory automatically, naming it by taking your class name and appending "Factory" on the end.
+  * [optional factory name] may be included to specify the name of an existing factory that should be used to construct your plugin. For example, if your class will not have any dependencies, you can use the simple Laminas\\ServiceManager\\Factory\\InvokableFactory to construct the object in a simple fashion. If you do not specify a factory name, the generator will create a factory automatically, naming it by taking your class name and appending "Factory" on the end.
+==== Notes ====
+:!: Be sure that MyModule already exists and is included in your VUFIND_LOCAL_MODULES environment variable, or the generator may not work correctly. If MyModule does not yet exist, you can re-run VuFind®'s install.php script to create it.
+:!: If things don't work right away after generating code, you may need to clear your local/cache directory to get rid of outdated configurations.
 ==== Example ====
@@ Line 190: / Line 195: @@
 Successfully updated /home/dkatz/vufind3/module/MyModule/config/module.config.php
 </code>
+===== Related Video =====
+See the [[videos:code_generators_1|Code Generators Part 1]] and [[videos:code_generators_2|Code Generators Part 2]] videos for some examples of code generators in action.
 ---- struct data ----
+properties.Page Owner :
 ----