From d2b2ee1332a77a0cb5bdf1690e71de8052c4e6f2 Mon Sep 17 00:00:00 2001 From: Patryk Gruszka Date: Mon, 15 Apr 2024 11:27:29 +0200 Subject: [PATCH 01/30] feat: [DPMMA-2550] point groups api docs --- docs/index.rst | 1 + docs/rest_api/contacts.rst | 253 +++++++++++++++++++++++++++++ docs/rest_api/point_groups.rst | 280 +++++++++++++++++++++++++++++++++ 3 files changed, 534 insertions(+) create mode 100644 docs/rest_api/point_groups.rst diff --git a/docs/index.rst b/docs/index.rst index 03a5b399..2ae565ad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -145,6 +145,7 @@ There are several ways to support Mautic other than contributing with code. rest_api/contacts rest_api/fields rest_api/notifications + rest_api/point_groups rest_api/reports rest_api/text_messages diff --git a/docs/rest_api/contacts.rst b/docs/rest_api/contacts.rst index 829a1d5a..205d6f8d 100644 --- a/docs/rest_api/contacts.rst +++ b/docs/rest_api/contacts.rst @@ -1055,6 +1055,259 @@ To subtract Points from a Contact and return a 404 if the Contact isn't found: "success": true } +Get All Contact Point Groups Scores +*********************************** + +Get all Point Group scores for a specific contact. + +**HTTP Request** + +``GET /api/contacts/{leadId}/points/groups`` + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "total": 1, + "groupScores": [ + { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + ] + } + +The response will contain a list of Point Group scores for the Contact. + +Get Single Contact Point Group Score +************************************ + +Get the score for a specific Point Group for a contact. + +**HTTP Request** + +``GET /api/contacts/{leadId}/points/groups/{groupId}`` + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will contain the score for the specified Point Group for the Contact. + +Add Contact Point Group Score +***************************** + +Add points to a specific Point Group for a contact. + +**HTTP Request** + +``POST /api/contacts/{leadId}/points/groups/{groupId}/plus/{value}`` + +**Data Parameters (optional)** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - ``eventname`` + - Name of the event + * - ``actionname`` + - Name of the action + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will indicate the success of adding points to the specified Point Group for the Contact. + +Subtract Contact Point Group Score +********************************** + +Subtract points from a specific Point Group for a contact. + +**HTTP Request** + +``POST /api/contacts/{leadId}/points/groups/{groupId}/minus/{value}`` + +**Data Parameters (optional)** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - ``eventname`` + - Name of the event + * - ``actionname`` + - Name of the action + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will indicate the success of subtracting points from the specified Point Group for the Contact. + +Set Contact Point Group Score +***************************** + +Set the points for a specific Point Group for a contact. + +**HTTP Request** + +``POST /api/contacts/{leadId}/points/groups/{groupId}/set/{value}`` + +**Data Parameters (optional)** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - ``eventname`` + - Name of the event + * - ``actionname`` + - Name of the action + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will indicate the success of setting the points for the specified Point Group for the Contact. + +Divide Contact Point Group Score +******************************** + +Divide the points of a specific Point Group for a contact by a value. + +**HTTP Request** + +``POST /api/contacts/{leadId}/points/groups/{groupId}/divide/{value}`` + +**Data Parameters (optional)** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - ``eventname`` + - Name of the event + * - ``actionname`` + - Name of the action + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will indicate the success of dividing the points of the specified Point Group for the Contact by the specified value. + +Multiply Contact Point Group Score +********************************** + +Multiply the points of a specific Point Group for a contact by a value. + +**HTTP Request** + +``POST /api/contacts/{leadId}/points/groups/{groupId}/times/{value}`` + +**Data Parameters (optional)** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - ``eventname`` + - Name of the event + * - ``actionname`` + - Name of the action + +**Response** + +``Expected Response Code: 200`` + +.. code-block:: json + + { + "groupScore": { + "score": 21, + "group": { + "id": 6, + "name": "A" + } + } + } + +The response will indicate the success of multiplying the points of the specified Point Group for the Contact by the specified value. + + .. vale off List Available Owners diff --git a/docs/rest_api/point_groups.rst b/docs/rest_api/point_groups.rst new file mode 100644 index 00000000..f7a1e6f5 --- /dev/null +++ b/docs/rest_api/point_groups.rst @@ -0,0 +1,280 @@ +Point Groups +############ + +Use this endpoint to manage Contact Point Groups in Mautic. + +.. code-block:: php + + newAuth($settings); + $apiUrl = "https://your-mautic.com"; + $api = new MauticApi(); + $pointGroupApi = $api->newApi("pointGroups", $auth, $apiUrl); + +Get Point Group +*************** + +.. code-block:: php + + get($id); + +.. code-block:: json + + "pointGroup": { + "id": 47, + "name": "Group A", + "description": "This is my first Point Group created via API.", + "isPublished": true, + "dateAdded": "2024-02-29T12:17:52+00:00", + "dateModified": null, + "createdBy": 2, + "createdByUser": "Admin User", + "modifiedBy": null, + "modifiedByUser": null, + } + +Get an individual Point Group by ID. + +**HTTP Request** + +``GET /points/groups/ID`` + +**Response** + +``Expected Response Code: 200`` + +See JSON code example. + +**Point Group Properties** + +.. list-table:: + :header-rows: 1 + + * - Name + - Type + - Description + * - id + - int + - ID of the Point Group + * - name + - string + - Point Group name + * - description + - string + - Point Group description + * - isPublished + - boolean + - Whether the Point Group is published + * - dateAdded + - datetime + - Date/time Point Group was created + * - createdBy + - int + - ID of the user that created the Point Group + * - createdByUser + - string + - Name of the user that created the Point Group + * - dateModified + - datetime/null + - Date/time Point Group was last modified + * - modifiedBy + - int + - ID of the user that last modified the Point Group + * - modifiedByUser + - string + - Name of the user that last modified the Point Group + +List Contact Point Groups +************************* + +.. code-block:: php + + getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal); + +.. code-block:: json + + { + "total": 4, + "pointGroups": [ + { + "id": 47, + "name": "Group A", + "description": "This is my first Point Group created via API.", + "isPublished": true, + "dateAdded": "2024-02-29T12:17:52+00:00", + "dateModified": null, + "createdBy": 2, + "createdByUser": "Admin User", + "modifiedBy": null, + "modifiedByUser": null + }, + ... + ] + } + +**HTTP Request** + +``GET /points/groups`` + +**Response** + +``Expected Response Code: 200`` + +See JSON code example. + +**Point Group Properties** + +.. list-table:: + :header-rows: 1 + + * - Name + - Type + - Description + * - total + - int + - Count of all Point Groups + * - id + - int + - ID of the Point Group + * - name + - string + - Point Group name + * - description + - string + - Point Group description + * - isPublished + - boolean + - Whether the Point Group is published + * - dateAdded + - datetime + - Date/time Point Group was created + * - createdBy + - int + - ID of the user that created the Point Group + * - createdByUser + - string + - Name of the user that created the Point Group + * - dateModified + - datetime/null + - Date/time Point Group was last modified + * - modifiedBy + - int + - ID of the user that last modified the Point Group + * - modifiedByUser + - string + - Name of the user that last modified the Point Group + +Create Point Group +****************** + +.. code-block:: php + + 'Group A', + 'description' => 'This is my first Point Group created via API.' + ]; + + $pointGroup = $pointGroupApi->create($data); + +Create a new Point Group. + +**HTTP Request** + +``POST /points/groups/new`` + +**Post Parameters** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - name + - Point Group name is the only required field + * - description + - A description of the Point Group. + +**Response** + +``Expected Response Code: 201`` + +**Properties** + +Same as `Get Point Group`. + +Edit Point Group +**************** + +.. code-block:: php + + 'New Point Group name', + 'description' => 'Updated description of the Point Group.' + ]; + + $pointGroup = $pointGroupApi->edit($id, $data); + +Edit a Point Group. + +**HTTP Request** + +``PATCH /points/groups/ID/edit`` + +**Post Parameters** + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + * - name + - Point Group name is the only required field + * - description + - A description of the Point Group. + +**Response** + +``Expected Response Code: 200`` + +**Properties** + +Same as `Get Point Group`. + +Delete Point Group +****************** + +.. code-block:: php + + delete($id); + +Delete a Point Group. + +**HTTP Request** + +``DELETE /points/groups/ID/delete`` + +**Response** + +``Expected Response Code: 200`` + +**Properties** + +Same as `Get Point Group`. \ No newline at end of file From 295e1a824453fb9ec23ca3ff8e9c4b1c49b712f0 Mon Sep 17 00:00:00 2001 From: Patryk Gruszka Date: Mon, 15 Apr 2024 13:12:09 +0200 Subject: [PATCH 02/30] fix: [DPMMA-2550] vale --- docs/rest_api/contacts.rst | 57 ++++++++++++++ docs/rest_api/point_groups.rst | 140 +++++++++++++++++++++++---------- 2 files changed, 156 insertions(+), 41 deletions(-) diff --git a/docs/rest_api/contacts.rst b/docs/rest_api/contacts.rst index 205d6f8d..102bdc92 100644 --- a/docs/rest_api/contacts.rst +++ b/docs/rest_api/contacts.rst @@ -1055,13 +1055,21 @@ To subtract Points from a Contact and return a 404 if the Contact isn't found: "success": true } +.. vale off + Get All Contact Point Groups Scores *********************************** +.. vale on + Get all Point Group scores for a specific contact. +.. vale off + **HTTP Request** +.. vale on + ``GET /api/contacts/{leadId}/points/groups`` **Response** @@ -1085,13 +1093,21 @@ Get all Point Group scores for a specific contact. The response will contain a list of Point Group scores for the Contact. +.. vale off + Get Single Contact Point Group Score ************************************ +.. vale on + Get the score for a specific Point Group for a contact. +.. vale off + **HTTP Request** +.. vale on + ``GET /api/contacts/{leadId}/points/groups/{groupId}`` **Response** @@ -1112,13 +1128,22 @@ Get the score for a specific Point Group for a contact. The response will contain the score for the specified Point Group for the Contact. +.. vale off + Add Contact Point Group Score ***************************** +.. vale on + Add points to a specific Point Group for a contact. +.. vale off + **HTTP Request** +.. vale on + + ``POST /api/contacts/{leadId}/points/groups/{groupId}/plus/{value}`` **Data Parameters (optional)** @@ -1151,13 +1176,21 @@ Add points to a specific Point Group for a contact. The response will indicate the success of adding points to the specified Point Group for the Contact. +.. vale off + Subtract Contact Point Group Score ********************************** +.. vale on + Subtract points from a specific Point Group for a contact. +.. vale off + **HTTP Request** +.. vale on + ``POST /api/contacts/{leadId}/points/groups/{groupId}/minus/{value}`` **Data Parameters (optional)** @@ -1190,13 +1223,21 @@ Subtract points from a specific Point Group for a contact. The response will indicate the success of subtracting points from the specified Point Group for the Contact. +.. vale off + Set Contact Point Group Score ***************************** +.. vale on + Set the points for a specific Point Group for a contact. +.. vale off + **HTTP Request** +.. vale on + ``POST /api/contacts/{leadId}/points/groups/{groupId}/set/{value}`` **Data Parameters (optional)** @@ -1229,13 +1270,21 @@ Set the points for a specific Point Group for a contact. The response will indicate the success of setting the points for the specified Point Group for the Contact. +.. vale off + Divide Contact Point Group Score ******************************** +.. vale on + Divide the points of a specific Point Group for a contact by a value. +.. vale off + **HTTP Request** +.. vale on + ``POST /api/contacts/{leadId}/points/groups/{groupId}/divide/{value}`` **Data Parameters (optional)** @@ -1268,13 +1317,21 @@ Divide the points of a specific Point Group for a contact by a value. The response will indicate the success of dividing the points of the specified Point Group for the Contact by the specified value. +.. vale off + Multiply Contact Point Group Score ********************************** +.. vale on + Multiply the points of a specific Point Group for a contact by a value. +.. vale off + **HTTP Request** +.. vale on + ``POST /api/contacts/{leadId}/points/groups/{groupId}/times/{value}`` **Data Parameters (optional)** diff --git a/docs/rest_api/point_groups.rst b/docs/rest_api/point_groups.rst index f7a1e6f5..efef0de0 100644 --- a/docs/rest_api/point_groups.rst +++ b/docs/rest_api/point_groups.rst @@ -1,6 +1,10 @@ +.. vale off + Point Groups ############ +.. vale on + Use this endpoint to manage Contact Point Groups in Mautic. .. code-block:: php @@ -16,9 +20,13 @@ Use this endpoint to manage Contact Point Groups in Mautic. $api = new MauticApi(); $pointGroupApi = $api->newApi("pointGroups", $auth, $apiUrl); +.. vale off + Get Point Group *************** +.. vale on + .. code-block:: php Date: Mon, 15 Apr 2024 14:29:36 +0200 Subject: [PATCH 03/30] Fix vale warnings and capitals Co-authored-by: Ruth Cheesley --- docs/rest_api/contacts.rst | 38 +++++++++++++++++----------------- docs/rest_api/point_groups.rst | 16 +++++++------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/rest_api/contacts.rst b/docs/rest_api/contacts.rst index 102bdc92..2630a392 100644 --- a/docs/rest_api/contacts.rst +++ b/docs/rest_api/contacts.rst @@ -1057,12 +1057,12 @@ To subtract Points from a Contact and return a 404 if the Contact isn't found: .. vale off -Get All Contact Point Groups Scores +Get all Contact Point Groups scores *********************************** .. vale on -Get all Point Group scores for a specific contact. +Get all Point Group scores for a specific Contact. .. vale off @@ -1091,16 +1091,16 @@ Get all Point Group scores for a specific contact. ] } -The response will contain a list of Point Group scores for the Contact. +The response contains a list of Point Group scores for the Contact. .. vale off -Get Single Contact Point Group Score +Get single Contact Point Group score ************************************ .. vale on -Get the score for a specific Point Group for a contact. +Get the score for a specific Point Group for a Contact. .. vale off @@ -1126,7 +1126,7 @@ Get the score for a specific Point Group for a contact. } } -The response will contain the score for the specified Point Group for the Contact. +The response contains the score for the specified Point Group for the Contact. .. vale off @@ -1135,7 +1135,7 @@ Add Contact Point Group Score .. vale on -Add points to a specific Point Group for a contact. +Add Points to a specific Point Group for a Contact. .. vale off @@ -1174,16 +1174,16 @@ Add points to a specific Point Group for a contact. } } -The response will indicate the success of adding points to the specified Point Group for the Contact. +The response indicates the success of adding Points to the specified Point Group for the Contact. .. vale off -Subtract Contact Point Group Score +Subtract Contact Point Group score ********************************** .. vale on -Subtract points from a specific Point Group for a contact. +Subtract Points from a specific Point Group for a Contact. .. vale off @@ -1221,7 +1221,7 @@ Subtract points from a specific Point Group for a contact. } } -The response will indicate the success of subtracting points from the specified Point Group for the Contact. +The response indicates the success of subtracting Points from the specified Point Group for the Contact. .. vale off @@ -1230,7 +1230,7 @@ Set Contact Point Group Score .. vale on -Set the points for a specific Point Group for a contact. +Set the Points for a specific Point Group for a Contact. .. vale off @@ -1268,16 +1268,16 @@ Set the points for a specific Point Group for a contact. } } -The response will indicate the success of setting the points for the specified Point Group for the Contact. +The response indicates the success of setting the Points for the specified Point Group for the Contact. .. vale off -Divide Contact Point Group Score +Divide Contact Point Group score ******************************** .. vale on -Divide the points of a specific Point Group for a contact by a value. +Divide the Points of a specific Point Group for a Contact by a value. .. vale off @@ -1315,16 +1315,16 @@ Divide the points of a specific Point Group for a contact by a value. } } -The response will indicate the success of dividing the points of the specified Point Group for the Contact by the specified value. +The response indicates the success of dividing the Points of the specified Point Group for the Contact by the specified value. .. vale off -Multiply Contact Point Group Score +Multiply Contact Point Group score ********************************** .. vale on -Multiply the points of a specific Point Group for a contact by a value. +Multiply the Points of a specific Point Group for a Contact by a value. .. vale off @@ -1362,7 +1362,7 @@ Multiply the points of a specific Point Group for a contact by a value. } } -The response will indicate the success of multiplying the points of the specified Point Group for the Contact by the specified value. +The response indicates the success of multiplying the Points of the specified Point Group for the Contact by the specified value. .. vale off diff --git a/docs/rest_api/point_groups.rst b/docs/rest_api/point_groups.rst index efef0de0..68005613 100644 --- a/docs/rest_api/point_groups.rst +++ b/docs/rest_api/point_groups.rst @@ -92,19 +92,19 @@ See JSON code example. - Date/time Point Group was created * - ``createdBy`` - ``int`` - - ID of the user that created the Point Group + - ID of the User that created the Point Group * - ``createdByUser`` - ``string`` - - Name of the user that created the Point Group + - Name of the User that created the Point Group * - ``dateModified`` - ``datetime/null`` - Date/time Point Group was last modified * - ``modifiedBy`` - ``int`` - - ID of the user that last modified the Point Group + - ID of the User that last modified the Point Group * - ``modifiedByUser`` - ``string`` - - Name of the user that last modified the Point Group + - Name of the User that last modified the Point Group .. vale off @@ -184,19 +184,19 @@ See JSON code example. - Date/time Point Group was created * - ``createdBy`` - ``int`` - - ID of the user that created the Point Group + - ID of the User that created the Point Group * - ``createdByUser`` - ``string`` - - Name of the user that created the Point Group + - Name of the User that created the Point Group * - ``dateModified`` - ``datetime/null`` - Date/time Point Group was last modified * - ``modifiedBy`` - ``int`` - - ID of the user that last modified the Point Group + - ID of the User that last modified the Point Group * - ``modifiedByUser`` - ``string`` - - Name of the user that last modified the Point Group + - Name of the User that last modified the Point Group .. vale off From f25b5f9cc084ac18e2394cb38bb7f13905b1d8e8 Mon Sep 17 00:00:00 2001 From: Patryk Gruszka Date: Mon, 15 Apr 2024 14:39:36 +0200 Subject: [PATCH 04/30] fix: [DPMMA-2550] remove unnecessary lines --- docs/rest_api/point_groups.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/rest_api/point_groups.rst b/docs/rest_api/point_groups.rst index efef0de0..1a234d09 100644 --- a/docs/rest_api/point_groups.rst +++ b/docs/rest_api/point_groups.rst @@ -217,8 +217,6 @@ Create Point Group $pointGroup = $pointGroupApi->create($data); -Create a new Point Group. - .. vale off **HTTP Request** @@ -271,8 +269,6 @@ Edit Point Group $pointGroup = $pointGroupApi->edit($id, $data); -Edit a Point Group. - .. vale off **HTTP Request** From 13138259b369a5ae2ccb3b386ff82e2a9e71f9f5 Mon Sep 17 00:00:00 2001 From: Tim Mallezie Date: Mon, 22 Apr 2024 20:14:35 +0200 Subject: [PATCH 05/30] Update forms.rst --- docs/components/forms.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/components/forms.rst b/docs/components/forms.rst index be33e29a..41af7f22 100644 --- a/docs/components/forms.rst +++ b/docs/components/forms.rst @@ -32,6 +32,10 @@ To add a custom Form Field, use the ``$event->addFormField($identifier, $paramet - Required - string - View template used to render the ``formType``, for example ``HelloWorldBundle:SubscribedEvents\FormField:customfield.html.php`` + * - ``help`` + - Optional + - string + - The language string for providing a help text below the form element. * - ``formTypeOptions`` - Optional - array From bf18daaa9cdddb8d08c908b4a2b53e26b4b2b23a Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:03:37 +0200 Subject: [PATCH 06/30] markdown version --- docs/plugins/from-4-to-5.rst | 101 +++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/plugins/from-4-to-5.rst diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst new file mode 100644 index 00000000..99a11e0b --- /dev/null +++ b/docs/plugins/from-4-to-5.rst @@ -0,0 +1,101 @@ +# Plugin upgrade from 4 to 5 step by step + +Here is a list of steps that most of the plugins will have to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your plugin. + +## 1. Continuous Integration + +If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html + +In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have local.php in config/local.php instead of app/config/local.php so update that as well. + +## 2. Autowiring + +Mautic 5 comes with autowiring which means developers will get way better developer experience and will be able to get things done faster. + +There is a great doc already written on this topic so get that setup and come back: https://devdocs.mautic.org/en/5.x/plugins/autowiring.html + +To quickly check that all services are passing you may find this command faster than refreshing the browser window: + +`rm -rf var/cache && bin/console` + +## 3. config.php - controllers + +config.php should be way lighter now when all services are gone after autowiring is configured. There is one more thing to check. The controllers are now defined with a different syntax. Here is an example: + +```php +- 'controller' => 'CronfigBundle:Cronfig:index', ++ 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' +``` + +Symfony 5 is way more explicit. We like that. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. + +## 4. Rendering viewes + +As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: + +https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md + +In the controllers, you'll also have to update the view paths like this: +```php +- $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php'); ++ $this->renderView('@MauticCore/Notification/flash_messages.html.twig'); +``` + +This command will save you some time as it validates the Twig syntax: + +`bin/console lint:twig plugins/MyBundle` + +_Update MyBundle with your bundle name._ + +## 5. The Integration Class + +If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. I bet this will be improved for Mautic 6, but for now add an alias to services.php: + +```php +$services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); +``` +_Replace `[MY_INTEGRAION]` with your plugin name._ + +## 6. Compiler passes + +If you plugin uses a compliler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: +```php +- ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); ++ ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') +``` + +## 7. Getting container in tests + +This one will be a quick find and replace: +```php +- $handlerStack = self::$container->get('mautic.http.client.mock_handler'); ++ $handlerStack = static::getContainer()->get(MockHandler::class); +``` +Notice you can also use FQCN instead of string service keys which is more convenient. + +## 8. Automated refactoring + +Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector will help you to upgrade for you. + +Run `bin/rector process plugins/MyBundle` and review the changes. + +_Update MyBundle with your bundle name._ + +## 9. Automated code style + +Another great way how to improve your plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. + +_Update MyBundle with your bundle name._ + +## 10. Static analysis + +PHPSTAN is another amazing tool that will find bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. + +Run `composer phpstan` + +If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a file and it will force you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. + +## Conclusion + +This list of steps is compiled by Mautic plugin developers for the Mautic plugin developers. If you find that some common problem isn't addressed here, please add it. + From 6b79b8d2eea9c7c9d2e5a36f68a501159e558d15 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:06:21 +0200 Subject: [PATCH 07/30] GPT used to convert to rst --- docs/plugins/from-4-to-5.rst | 56 ++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 99a11e0b..a7834384 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -1,14 +1,17 @@ -# Plugin upgrade from 4 to 5 step by step +Plugin upgrade from 4 to 5 step by step +========================================= Here is a list of steps that most of the plugins will have to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your plugin. -## 1. Continuous Integration +1. Continuous Integration +----------------------- If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have local.php in config/local.php instead of app/config/local.php so update that as well. -## 2. Autowiring +2. Autowiring +---------- Mautic 5 comes with autowiring which means developers will get way better developer experience and will be able to get things done faster. @@ -16,64 +19,65 @@ There is a great doc already written on this topic so get that setup and come ba To quickly check that all services are passing you may find this command faster than refreshing the browser window: -`rm -rf var/cache && bin/console` +rm -rf var/cache && bin/console -## 3. config.php - controllers +3. config.php - controllers +------------------------- config.php should be way lighter now when all services are gone after autowiring is configured. There is one more thing to check. The controllers are now defined with a different syntax. Here is an example: -```php - 'controller' => 'CronfigBundle:Cronfig:index', + 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' -``` Symfony 5 is way more explicit. We like that. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. -## 4. Rendering viewes +4. Rendering views +---------------- As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md In the controllers, you'll also have to update the view paths like this: -```php + - $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php'); + $this->renderView('@MauticCore/Notification/flash_messages.html.twig'); -``` This command will save you some time as it validates the Twig syntax: -`bin/console lint:twig plugins/MyBundle` +bin/console lint:twig plugins/MyBundle _Update MyBundle with your bundle name._ -## 5. The Integration Class +5. The Integration Class +---------------------- If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. I bet this will be improved for Mautic 6, but for now add an alias to services.php: -```php $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); -``` + _Replace `[MY_INTEGRAION]` with your plugin name._ -## 6. Compiler passes +6. Compiler passes +---------------- If you plugin uses a compliler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: -```php + - ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); + ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') -``` -## 7. Getting container in tests +7. Getting container in tests +--------------------------- This one will be a quick find and replace: -```php + - $handlerStack = self::$container->get('mautic.http.client.mock_handler'); + $handlerStack = static::getContainer()->get(MockHandler::class); -``` + Notice you can also use FQCN instead of string service keys which is more convenient. -## 8. Automated refactoring +8. Automated refactoring +---------------------- Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector will help you to upgrade for you. @@ -81,13 +85,15 @@ Run `bin/rector process plugins/MyBundle` and review the changes. _Update MyBundle with your bundle name._ -## 9. Automated code style +9. Automated code style +--------------------- Another great way how to improve your plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. _Update MyBundle with your bundle name._ -## 10. Static analysis +10. Static analysis +---------------- PHPSTAN is another amazing tool that will find bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. @@ -95,7 +101,7 @@ Run `composer phpstan` If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a file and it will force you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. -## Conclusion +Conclusion +----------- This list of steps is compiled by Mautic plugin developers for the Mautic plugin developers. If you find that some common problem isn't addressed here, please add it. - From a2f13ccd7fdfbd81357891bce6088dd609d26ed4 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:07:14 +0200 Subject: [PATCH 08/30] Adding notes --- docs/plugins/from-4-to-5.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index a7834384..00e94a7a 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -47,7 +47,7 @@ This command will save you some time as it validates the Twig syntax: bin/console lint:twig plugins/MyBundle -_Update MyBundle with your bundle name._ +.. note:: Update MyBundle with your bundle name. 5. The Integration Class ---------------------- @@ -56,7 +56,7 @@ If you went ahead and deleted all services from config.php with a smile on your $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); -_Replace `[MY_INTEGRAION]` with your plugin name._ +.. note:: Replace `[MY_INTEGRAION]` with your plugin name. 6. Compiler passes ---------------- @@ -83,14 +83,14 @@ Your plugin should be working on Mautic 5 by now. But let's go further as Mautic Run `bin/rector process plugins/MyBundle` and review the changes. -_Update MyBundle with your bundle name._ +.. note:: Update MyBundle with your bundle name. 9. Automated code style --------------------- Another great way how to improve your plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. -_Update MyBundle with your bundle name._ +.. note:: Update MyBundle with your bundle name. 10. Static analysis ---------------- From f23c33f6154b151bb0a9780aac8ec083c5c02aa4 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:13:35 +0200 Subject: [PATCH 09/30] Code samples styled --- docs/plugins/from-4-to-5.rst | 57 +++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 00e94a7a..3e9fc0c0 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -4,14 +4,14 @@ Plugin upgrade from 4 to 5 step by step Here is a list of steps that most of the plugins will have to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your plugin. 1. Continuous Integration ------------------------ +------------------------- If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have local.php in config/local.php instead of app/config/local.php so update that as well. 2. Autowiring ----------- +------------- Mautic 5 comes with autowiring which means developers will get way better developer experience and will be able to get things done faster. @@ -19,20 +19,22 @@ There is a great doc already written on this topic so get that setup and come ba To quickly check that all services are passing you may find this command faster than refreshing the browser window: -rm -rf var/cache && bin/console +``rm -rf var/cache && bin/console`` 3. config.php - controllers -------------------------- +--------------------------- config.php should be way lighter now when all services are gone after autowiring is configured. There is one more thing to check. The controllers are now defined with a different syntax. Here is an example: -- 'controller' => 'CronfigBundle:Cronfig:index', -+ 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' +.. code:: diff + + - 'controller' => 'CronfigBundle:Cronfig:index', + + 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' Symfony 5 is way more explicit. We like that. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. 4. Rendering views ----------------- +------------------ As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: @@ -40,68 +42,75 @@ https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md In the controllers, you'll also have to update the view paths like this: -- $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php'); -+ $this->renderView('@MauticCore/Notification/flash_messages.html.twig'); +.. code:: diff + + - $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php'); + + $this->renderView('@MauticCore/Notification/flash_messages.html.twig'); This command will save you some time as it validates the Twig syntax: -bin/console lint:twig plugins/MyBundle +``bin/console lint:twig plugins/MyBundle`` .. note:: Update MyBundle with your bundle name. 5. The Integration Class ----------------------- +------------------------ If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. I bet this will be improved for Mautic 6, but for now add an alias to services.php: -$services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); +.. code:: php + $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); .. note:: Replace `[MY_INTEGRAION]` with your plugin name. 6. Compiler passes ----------------- +------------------ If you plugin uses a compliler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: -- ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); -+ ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') +.. code:: diff + + - ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); + + ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') 7. Getting container in tests ---------------------------- +----------------------------- This one will be a quick find and replace: -- $handlerStack = self::$container->get('mautic.http.client.mock_handler'); -+ $handlerStack = static::getContainer()->get(MockHandler::class); +.. code:: diff + + - $handlerStack = self::$container->get('mautic.http.client.mock_handler'); + + $handlerStack = static::getContainer()->get(MockHandler::class); Notice you can also use FQCN instead of string service keys which is more convenient. 8. Automated refactoring ----------------------- +------------------------ Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector will help you to upgrade for you. -Run `bin/rector process plugins/MyBundle` and review the changes. +Run ``bin/rector process plugins/MyBundle`` and review the changes. .. note:: Update MyBundle with your bundle name. 9. Automated code style ---------------------- +----------------------- Another great way how to improve your plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. .. note:: Update MyBundle with your bundle name. 10. Static analysis ----------------- +------------------- PHPSTAN is another amazing tool that will find bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. -Run `composer phpstan` +Run ``composer phpstan`` If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a file and it will force you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. Conclusion ------------ +---------- This list of steps is compiled by Mautic plugin developers for the Mautic plugin developers. If you find that some common problem isn't addressed here, please add it. From cb6ac0b6761cf6481136f652a70c53dedca3d9ea Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:17:38 +0200 Subject: [PATCH 10/30] Adding index --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index 03a5b399..793f5b52 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,6 +105,7 @@ There are several ways to support Mautic other than contributing with code. plugins/data plugins/translations plugins/continuous-integration + plugins/from-4-to-5 .. toctree:: :maxdepth: 2 From c56d1c42369f02cce49fd59652bdece5711024c0 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Tue, 23 Apr 2024 19:22:46 +0200 Subject: [PATCH 11/30] Note about removing services --- docs/plugins/from-4-to-5.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 3e9fc0c0..81f70b7b 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -21,6 +21,8 @@ To quickly check that all services are passing you may find this command faster ``rm -rf var/cache && bin/console`` +.. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file. But do that as a cherry on top once you are sure everything is working. See step 5 that could get you stuck good. There may be others like it. + 3. config.php - controllers --------------------------- From d9dce979533b98c2ef35d483bcf84469d2fae674 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Wed, 24 Apr 2024 20:49:08 +0200 Subject: [PATCH 12/30] Vale? --- docs/plugins/from-4-to-5.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 81f70b7b..56e606fb 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -1,23 +1,23 @@ Plugin upgrade from 4 to 5 step by step -========================================= +======================================= -Here is a list of steps that most of the plugins will have to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your plugin. +Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin. 1. Continuous Integration ------------------------- If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html -In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have local.php in config/local.php instead of app/config/local.php so update that as well. +In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. 2. Autowiring ------------- -Mautic 5 comes with autowiring which means developers will get way better developer experience and will be able to get things done faster. +Mautic 5 comes with autowiring of PHP services which means the developer experience is way better and the code will shrink substantially. There is a great doc already written on this topic so get that setup and come back: https://devdocs.mautic.org/en/5.x/plugins/autowiring.html -To quickly check that all services are passing you may find this command faster than refreshing the browser window: +To quickly check that all services are wired and configured correctly you may find this command faster than refreshing the browser window: ``rm -rf var/cache && bin/console`` From d43ed26a5c2b0642a2537152945b35f983e0fc7e Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Thu, 25 Apr 2024 21:27:01 +0200 Subject: [PATCH 13/30] removing "will" --- docs/plugins/from-4-to-5.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 56e606fb..b891b9f7 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -13,7 +13,7 @@ In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 2. Autowiring ------------- -Mautic 5 comes with autowiring of PHP services which means the developer experience is way better and the code will shrink substantially. +Mautic 5 comes with autowiring of PHP services which means the developer experience is way better and the code size gets reduced. There is a great doc already written on this topic so get that setup and come back: https://devdocs.mautic.org/en/5.x/plugins/autowiring.html @@ -49,7 +49,7 @@ In the controllers, you'll also have to update the view paths like this: - $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php'); + $this->renderView('@MauticCore/Notification/flash_messages.html.twig'); -This command will save you some time as it validates the Twig syntax: +Running this command is faster than refreshing all the views in the browser. It validates the Twig syntax and can guide you through the process: ``bin/console lint:twig plugins/MyBundle`` @@ -58,7 +58,7 @@ This command will save you some time as it validates the Twig syntax: 5. The Integration Class ------------------------ -If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. I bet this will be improved for Mautic 6, but for now add an alias to services.php: +If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. This should be improved for Mautic 6, but for now add an alias to services.php: .. code:: php $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); @@ -78,7 +78,7 @@ If you plugin uses a compliler pass, you may have to double-check that it works 7. Getting container in tests ----------------------------- -This one will be a quick find and replace: +This one is a quick find and replace: .. code:: diff @@ -90,7 +90,7 @@ Notice you can also use FQCN instead of string service keys which is more conven 8. Automated refactoring ------------------------ -Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector will help you to upgrade for you. +Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector upgrade the code for you. Run ``bin/rector process plugins/MyBundle`` and review the changes. @@ -106,11 +106,11 @@ Another great way how to improve your plugin code base quality is to run the CS 10. Static analysis ------------------- -PHPSTAN is another amazing tool that will find bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. +PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. Run ``composer phpstan`` -If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a file and it will force you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. +If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. Conclusion ---------- From 0f210021d41b433e4d1d333cb7a38d589b4dbc50 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Thu, 25 Apr 2024 21:40:33 +0200 Subject: [PATCH 14/30] Vale --- docs/plugins/from-4-to-5.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index b891b9f7..f47c0728 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -33,12 +33,12 @@ config.php should be way lighter now when all services are gone after autowiring - 'controller' => 'CronfigBundle:Cronfig:index', + 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' -Symfony 5 is way more explicit. We like that. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. +Symfony 5 is way more explicit. That's a good thing even if it's longer! You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. -4. Rendering views +4. Rendering Views ------------------ -As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: +As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your Plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md @@ -58,17 +58,17 @@ Running this command is faster than refreshing all the views in the browser. It 5. The Integration Class ------------------------ -If you went ahead and deleted all services from config.php with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. This should be improved for Mautic 6, but for now add an alias to services.php: +If you went ahead and deleted all services from ``config.php`` with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. This should be improved for Mautic 6, but for now add an alias to ``services.php``: .. code:: php $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); -.. note:: Replace `[MY_INTEGRAION]` with your plugin name. +.. note:: Replace `[MY_INTEGRAION]` with your Plugin name. -6. Compiler passes +6. Compiler Passes ------------------ -If you plugin uses a compliler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: +If you Plugin uses a compiler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: .. code:: diff @@ -87,23 +87,23 @@ This one is a quick find and replace: Notice you can also use FQCN instead of string service keys which is more convenient. -8. Automated refactoring +8. Automated Refactoring ------------------------ -Your plugin should be working on Mautic 5 by now. But let's go further as Mautic 5 uses PHP 8+ we can take advantage of the syntax. And Rector upgrade the code for you. +Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. And Rector can upgrade the code for you. Run ``bin/rector process plugins/MyBundle`` and review the changes. .. note:: Update MyBundle with your bundle name. -9. Automated code style +9. Automated Code Style ----------------------- -Another great way how to improve your plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. +Another great way how to improve your Plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. .. note:: Update MyBundle with your bundle name. -10. Static analysis +10. Static Analysis ------------------- PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. @@ -115,4 +115,4 @@ If your plugin has way too many PHPSTAN errors than you can handle right now, co Conclusion ---------- -This list of steps is compiled by Mautic plugin developers for the Mautic plugin developers. If you find that some common problem isn't addressed here, please add it. +This list of steps is compiled by Mautic Plugin developers for the Mautic Plugin developers. If you find that some common problem isn't addressed here, please add it. From 215e3052bc9294a8042484469682327bb9949412 Mon Sep 17 00:00:00 2001 From: Jan Linhart Date: Thu, 25 Apr 2024 21:44:58 +0200 Subject: [PATCH 15/30] More Vale --- docs/plugins/from-4-to-5.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index f47c0728..10e6fd27 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -3,14 +3,14 @@ Plugin upgrade from 4 to 5 step by step Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin. -1. Continuous Integration +1) Continuous Integration ------------------------- If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. -2. Autowiring +2) Autowiring ------------- Mautic 5 comes with autowiring of PHP services which means the developer experience is way better and the code size gets reduced. @@ -23,7 +23,7 @@ To quickly check that all services are wired and configured correctly you may fi .. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file. But do that as a cherry on top once you are sure everything is working. See step 5 that could get you stuck good. There may be others like it. -3. config.php - controllers +3) config.php - controllers --------------------------- config.php should be way lighter now when all services are gone after autowiring is configured. There is one more thing to check. The controllers are now defined with a different syntax. Here is an example: @@ -33,9 +33,9 @@ config.php should be way lighter now when all services are gone after autowiring - 'controller' => 'CronfigBundle:Cronfig:index', + 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' -Symfony 5 is way more explicit. That's a good thing even if it's longer! You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. +Symfony 5 is way more explicit. That's a good thing even if it's longer. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. -4. Rendering Views +4) Rendering Views ------------------ As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your Plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: @@ -55,7 +55,7 @@ Running this command is faster than refreshing all the views in the browser. It .. note:: Update MyBundle with your bundle name. -5. The Integration Class +5) The Integration Class ------------------------ If you went ahead and deleted all services from ``config.php`` with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. This should be improved for Mautic 6, but for now add an alias to ``services.php``: @@ -65,7 +65,7 @@ If you went ahead and deleted all services from ``config.php`` with a smile on y .. note:: Replace `[MY_INTEGRAION]` with your Plugin name. -6. Compiler Passes +6) Compiler Passes ------------------ If you Plugin uses a compiler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: @@ -75,7 +75,7 @@ If you Plugin uses a compiler pass, you may have to double-check that it works c - ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); + ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') -7. Getting container in tests +7) Getting container in tests ----------------------------- This one is a quick find and replace: @@ -87,7 +87,7 @@ This one is a quick find and replace: Notice you can also use FQCN instead of string service keys which is more convenient. -8. Automated Refactoring +8) Automated Refactoring ------------------------ Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. And Rector can upgrade the code for you. @@ -96,14 +96,14 @@ Run ``bin/rector process plugins/MyBundle`` and review the changes. .. note:: Update MyBundle with your bundle name. -9. Automated Code Style +9) Automated Code Style ----------------------- Another great way how to improve your Plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. .. note:: Update MyBundle with your bundle name. -10. Static Analysis +10) Static Analysis ------------------- PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. From 0a3f317e616d1f5322bf9daea3b89790cf298788 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Fri, 26 Apr 2024 09:58:33 +0000 Subject: [PATCH 16/30] Add link file --- docs/links/mautic_php_to_twig.py | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/links/mautic_php_to_twig.py diff --git a/docs/links/mautic_php_to_twig.py b/docs/links/mautic_php_to_twig.py new file mode 100644 index 00000000..fff2e8dd --- /dev/null +++ b/docs/links/mautic_php_to_twig.py @@ -0,0 +1,7 @@ +from . import link + +link_name = "PHP to Twig migration" +link_text = "Upgrading PHP to Twig templates" +link_url = "https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md" + +link.xref_links.update({link_name: (link_text, link_url)}) From ecd012588a2bca71fc07d6fce0a9c2c69c0e44c0 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:07:17 +0200 Subject: [PATCH 17/30] wiring rewording Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 10e6fd27..3d3e6a18 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -17,7 +17,7 @@ Mautic 5 comes with autowiring of PHP services which means the developer experie There is a great doc already written on this topic so get that setup and come back: https://devdocs.mautic.org/en/5.x/plugins/autowiring.html -To quickly check that all services are wired and configured correctly you may find this command faster than refreshing the browser window: +To quickly verify that the wiring of services is complete and configured correctly you may find this command faster than refreshing the browser window: ``rm -rf var/cache && bin/console`` From 1e712aa8dc9ef9ded554e554d402115c88cf4d67 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:10:04 +0200 Subject: [PATCH 18/30] heading improvement Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 3d3e6a18..db6eca82 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -1,4 +1,4 @@ -Plugin upgrade from 4 to 5 step by step +Update plugins for Mautic 5 ======================================= Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin. From 6bd40c6a9aea6759723de1379af23793a3b73fa7 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:12:30 +0200 Subject: [PATCH 19/30] Apply suggestions from code review wording improvements Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index db6eca82..58386ec7 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -8,37 +8,37 @@ Here is a list of steps that most of the Plugins may need to take to upgrade fro If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html -In your PR add also PHP 8.1 and 8.2. And upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. +In your PR add also support for PHP 8.1 and 8.2, and upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. 2) Autowiring ------------- -Mautic 5 comes with autowiring of PHP services which means the developer experience is way better and the code size gets reduced. +Mautic 5 comes with autowiring of PHP services which means the developer experience is much improved, and the code size is reduced. -There is a great doc already written on this topic so get that setup and come back: https://devdocs.mautic.org/en/5.x/plugins/autowiring.html +There is a great doc already written on this topic: :doc:`/plugins/autowiring` - so refer to that for instructions. To quickly verify that the wiring of services is complete and configured correctly you may find this command faster than refreshing the browser window: ``rm -rf var/cache && bin/console`` -.. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file. But do that as a cherry on top once you are sure everything is working. See step 5 that could get you stuck good. There may be others like it. + .. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file, but do that as a cherry on top once you are sure everything is working as the later steps in this process may yet cause you difficulties. 3) config.php - controllers --------------------------- -config.php should be way lighter now when all services are gone after autowiring is configured. There is one more thing to check. The controllers are now defined with a different syntax. Here is an example: +``config.php`` should be much lighter now when all services are gone after autowiring is configured. There is one more thing to verify. The controllers are now defined with a different syntax. Here is an example: .. code:: diff - 'controller' => 'CronfigBundle:Cronfig:index', + 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction' -Symfony 5 is way more explicit. That's a good thing even if it's longer. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` anymore. Your choice. +Symfony 5 is much more explicit. That's a good thing even if it's longer. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` any more. 4) Rendering Views ------------------ -As the PHP templating engine was removed from Symfony 5, Mautic had to switch to Twig. And your Plugin must follow. Here is a helpful resource on how to migrate the `*.html.php` files to `*.html.twig` files: +As Symfony 5 removed the PHP templating engine, Mautic had to switch to Twig. Your Plugin must also update the any views from PHP to Twig. Here is a helpful resource on how to migrate the ``*.html.php`` files to ``*.html.twig`` files: https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md @@ -58,7 +58,7 @@ Running this command is faster than refreshing all the views in the browser. It 5) The Integration Class ------------------------ -If you went ahead and deleted all services from ``config.php`` with a smile on your face, you may find yourself in a pickle if you are using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your integration has a service key in a specific format. This should be improved for Mautic 6, but for now add an alias to ``services.php``: +If you went ahead and deleted all services from ``config.php``, you may experience problems if you're using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your Integration has a service key in a specific format. Mautic 6 aims to improve this, but for now, add an alias to ``services.php``: .. code:: php $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); @@ -68,7 +68,7 @@ If you went ahead and deleted all services from ``config.php`` with a smile on y 6) Compiler Passes ------------------ -If you Plugin uses a compiler pass, you may have to double-check that it works correctly. In many cases you may have to change the service alias with FQCN like so: +If your Plugin uses a compiler pass, you may have to verify that it works correctly. In many cases you may have to change the service alias with FQCN like so: .. code:: diff @@ -90,7 +90,7 @@ Notice you can also use FQCN instead of string service keys which is more conven 8) Automated Refactoring ------------------------ -Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. And Rector can upgrade the code for you. +Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. Rector can upgrade the code for you. Run ``bin/rector process plugins/MyBundle`` and review the changes. @@ -106,11 +106,11 @@ Another great way how to improve your Plugin code base quality is to run the CS 10) Static Analysis ------------------- -PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic so it's aware of all classes. +PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic, so it's aware of all classes. Run ``composer phpstan`` -If your plugin has way too many PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. +If your Plugin has more PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. Conclusion ---------- From bead4476551ec2a3da9d1f106f9b67bb802af988 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:14:46 +0200 Subject: [PATCH 20/30] Apply suggestions from code review Link improvements Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 58386ec7..a2ed166a 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -6,7 +6,7 @@ Here is a list of steps that most of the Plugins may need to take to upgrade fro 1) Continuous Integration ------------------------- -If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: https://devdocs.mautic.org/en/5.x/plugins/continuous-integration.html +If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: :doc:`/plugins/continuous-integration`. In your PR add also support for PHP 8.1 and 8.2, and upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. @@ -40,7 +40,7 @@ Symfony 5 is much more explicit. That's a good thing even if it's longer. You do As Symfony 5 removed the PHP templating engine, Mautic had to switch to Twig. Your Plugin must also update the any views from PHP to Twig. Here is a helpful resource on how to migrate the ``*.html.php`` files to ``*.html.twig`` files: -https://github.com/mautic/mautic/blob/5.x/UPGRADE-PHP-TO-TWIG-TEMPLATES.md +:xref:`PHP to Twig migration` In the controllers, you'll also have to update the view paths like this: From bfd3815215d3db030097b7f6fc75833a5fae29a6 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:17:36 +0200 Subject: [PATCH 21/30] Apply suggestions from code review Removing ordered list from headings Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index a2ed166a..2264b9d7 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -3,14 +3,14 @@ Update plugins for Mautic 5 Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin. -1) Continuous Integration +Continuous Integration ------------------------- If you don't have CI configured, this is the time to do it. This is an optional step but it makes sense to do it at the beginning rather than later. Here's how to get it done: :doc:`/plugins/continuous-integration`. In your PR add also support for PHP 8.1 and 8.2, and upgrade the Mautic version from 4.4 to 5.1. One more thing is that Mautic 5 have ``local.php`` in ``config/local.php`` instead of ``app/config/local.php`` so update that as well. -2) Autowiring +Autowiring ------------- Mautic 5 comes with autowiring of PHP services which means the developer experience is much improved, and the code size is reduced. @@ -23,7 +23,7 @@ To quickly verify that the wiring of services is complete and configured correct .. note:: Ideally, you should be able to delete the whole ``services`` section from your ``config.php`` file, but do that as a cherry on top once you are sure everything is working as the later steps in this process may yet cause you difficulties. -3) config.php - controllers +``config.php`` - controllers --------------------------- ``config.php`` should be much lighter now when all services are gone after autowiring is configured. There is one more thing to verify. The controllers are now defined with a different syntax. Here is an example: @@ -35,7 +35,7 @@ To quickly verify that the wiring of services is complete and configured correct Symfony 5 is much more explicit. That's a good thing even if it's longer. You don't have to guess what the syntax is. It's basically just standard FQCN (Fully Qualified Class Name) with the full method name behind the 2 colons. You don't even need to call the controller method `*Action` any more. -4) Rendering Views +Rendering views ------------------ As Symfony 5 removed the PHP templating engine, Mautic had to switch to Twig. Your Plugin must also update the any views from PHP to Twig. Here is a helpful resource on how to migrate the ``*.html.php`` files to ``*.html.twig`` files: @@ -55,7 +55,9 @@ Running this command is faster than refreshing all the views in the browser. It .. note:: Update MyBundle with your bundle name. -5) The Integration Class +.. vale off + +The Integration class ------------------------ If you went ahead and deleted all services from ``config.php``, you may experience problems if you're using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your Integration has a service key in a specific format. Mautic 6 aims to improve this, but for now, add an alias to ``services.php``: @@ -65,7 +67,7 @@ If you went ahead and deleted all services from ``config.php``, you may experien .. note:: Replace `[MY_INTEGRAION]` with your Plugin name. -6) Compiler Passes +Compiler passes ------------------ If your Plugin uses a compiler pass, you may have to verify that it works correctly. In many cases you may have to change the service alias with FQCN like so: @@ -75,7 +77,7 @@ If your Plugin uses a compiler pass, you may have to verify that it works correc - ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner'); + ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner') -7) Getting container in tests +Getting container in tests ----------------------------- This one is a quick find and replace: @@ -87,7 +89,7 @@ This one is a quick find and replace: Notice you can also use FQCN instead of string service keys which is more convenient. -8) Automated Refactoring +Automated refactoring ------------------------ Your Plugin should be working on Mautic 5 by now. Wouldn't it be great to shorten the code a little more? Mautic 5 uses PHP 8.0+ so can take advantage of the syntax. Rector can upgrade the code for you. @@ -96,14 +98,14 @@ Run ``bin/rector process plugins/MyBundle`` and review the changes. .. note:: Update MyBundle with your bundle name. -9) Automated Code Style +Automated code style ----------------------- Another great way how to improve your Plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. .. note:: Update MyBundle with your bundle name. -10) Static Analysis +Static analysis ------------------- PHPSTAN is another amazing tool that detects bugs for you. It's better to run it on the whole codebase including core Mautic, so it's aware of all classes. From d3dd9e77d06e263aa472ac073a80a3e778cc2696 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:18:10 +0200 Subject: [PATCH 22/30] Apply suggestions from code review Formating fixes Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index 2264b9d7..aaf36d11 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -60,9 +60,13 @@ Running this command is faster than refreshing all the views in the browser. It The Integration class ------------------------ +.. vale on + + If you went ahead and deleted all services from ``config.php``, you may experience problems if you're using Mautic's Integration classes and interfaces. The inner workings of the IntegrationsBundle expects that your Integration has a service key in a specific format. Mautic 6 aims to improve this, but for now, add an alias to ``services.php``: .. code:: php + $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); .. note:: Replace `[MY_INTEGRAION]` with your Plugin name. @@ -101,7 +105,7 @@ Run ``bin/rector process plugins/MyBundle`` and review the changes. Automated code style ----------------------- -Another great way how to improve your Plugin code base quality is to run the CS Fixer: `bin/php-cs-fixer fix plugins/MyBundle`. +Another great way how to improve your Plugin code base quality is to run the CS Fixer: ``bin/php-cs-fixer fix plugins/MyBundle``. .. note:: Update MyBundle with your bundle name. From 01af36590e5512852b6a92a0a17ce39a7b2467da Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 12:18:37 +0200 Subject: [PATCH 23/30] Apply suggestions from code review Typo fixes Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index aaf36d11..d633516e 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -67,9 +67,9 @@ If you went ahead and deleted all services from ``config.php``, you may experien .. code:: php - $services->alias('mautic.integration.[MY_INTEGRAION]', \MauticPlugin\[MY_INTEGRAION]Bundle\Integration\[MY_INTEGRAION]Integration::class); + $services->alias('mautic.integration.[MY_INTEGRATION]', \MauticPlugin\[MY_INTEGRATION]Bundle\Integration\[MY_INTEGRATION]Integration::class); -.. note:: Replace `[MY_INTEGRAION]` with your Plugin name. +.. note:: Replace `[MY_INTEGRATION]` with your Plugin name. Compiler passes ------------------ From b23b8c1b08ce024a3506a9ece1f9d2906baf4d68 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 13:09:10 +0200 Subject: [PATCH 24/30] Capital P Co-authored-by: Ruth Cheesley --- docs/plugins/from-4-to-5.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index d633516e..f8d7dea6 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -1,4 +1,4 @@ -Update plugins for Mautic 5 +Update Plugins for Mautic 5 ======================================= Here is a list of steps that most of the Plugins may need to take to upgrade from Mautic 4 to Mautic 5. You should be able to get through each step, make a commit, move to the next one and once you are at finished you have upgraded your Plugin. From e0ec327ba298c1927b308117ea3d82360d1d0c9c Mon Sep 17 00:00:00 2001 From: John Linhart Date: Fri, 26 Apr 2024 13:10:55 +0200 Subject: [PATCH 25/30] Removing link as it's a pain to manage it. --- docs/plugins/from-4-to-5.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index f8d7dea6..b197dc31 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -116,7 +116,7 @@ PHPSTAN is another amazing tool that detects bugs for you. It's better to run it Run ``composer phpstan`` -If your Plugin has more PHPSTAN errors than you can handle right now, consider using [PHPSTAN baseline](https://phpstan.org/user-guide/baseline). It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. +If your Plugin has more PHPSTAN errors than you can handle right now, consider using PHPSTAN baseline. It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. Conclusion ---------- From 8035f8abcc9bab2b8f418c9f4321a157698d0582 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Fri, 26 Apr 2024 11:14:53 +0000 Subject: [PATCH 26/30] Add PHPSTAN baseline link --- docs/links/phpstan_baseline.py | 7 +++++++ docs/plugins/from-4-to-5.rst | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/links/phpstan_baseline.py diff --git a/docs/links/phpstan_baseline.py b/docs/links/phpstan_baseline.py new file mode 100644 index 00000000..45c3a3b0 --- /dev/null +++ b/docs/links/phpstan_baseline.py @@ -0,0 +1,7 @@ +from . import link + +link_name = "PHPSTAN baseline" +link_text = "PHPSTAN baseline" +link_url = "https://phpstan.org/user-guide/baseline" + +link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/plugins/from-4-to-5.rst b/docs/plugins/from-4-to-5.rst index b197dc31..7e759b43 100644 --- a/docs/plugins/from-4-to-5.rst +++ b/docs/plugins/from-4-to-5.rst @@ -116,7 +116,7 @@ PHPSTAN is another amazing tool that detects bugs for you. It's better to run it Run ``composer phpstan`` -If your Plugin has more PHPSTAN errors than you can handle right now, consider using PHPSTAN baseline. It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. +If your Plugin has more PHPSTAN errors than you can handle right now, consider using :xref:`PHPSTAN baseline`. It allows you to store your tech debt to a single file and it forces you to write better code from now on. And you can reduce the baseline by small chunks every month to get to 0. Conclusion ---------- From 08e1f9fbe5d19ac3effd309110898067fc65575c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Pokorn=C3=BD?= Date: Thu, 23 May 2024 21:33:41 +0200 Subject: [PATCH 27/30] How to modify form templates in custom theme --- docs/themes/forms.rst | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/themes/forms.rst b/docs/themes/forms.rst index 849db166..78c35fec 100644 --- a/docs/themes/forms.rst +++ b/docs/themes/forms.rst @@ -3,11 +3,34 @@ Customizing Forms To provide custom Form field templates or to manipulate the Form body, create the following directory structure:: + Field/ <– for customizing form field types html/ - MauticFormBundle - Builder <– for customizing the form structure itself - Field <– for customizing form field types + MauticFormBundle/ + Builder/ + _style.html.twig <– for customizing CSS for Form + form.html.twig <– for customizing the form structure itself -Copy from ``app/bundles/FormBundle/Views/Builder/form.html.php`` into the Theme’s Builder directory and/or one or more of the fields templates in ``app/bundles/FormBundle/Views/Field/*.html.php`` into the Theme’s `field` directory. Then customize to the desired layout. Note that these must be PHP templates. +Copy from ``app/bundles/FormBundle/Resources/views/form.html.twig`` into the Theme’s Builder directory and/or one or more of the fields templates in ``app/bundles/FormBundle/Views/Field/*.html.php`` into the Theme’s `field` directory. Then customize to the desired layout. -You can add a custom style sheet to the Form by adding a ``style.html.twig`` with your custom CSS to ``html/MauticFormBundle/Builder``. The best way is to copy the content of the default Form styles and modify them to your needs. +You can add a custom style sheet to the Form by adding a ``_style.html.twig`` with your custom CSS to ``html/MauticFormBundle/Builder``. The best way is to copy the content of the default Form styles and modify them to your needs. + +Customize field types +********************* + +For change HTML generated by field types, you can create a new template in the `Field` directory. +I recommend copy the original template from `app/bundles/FormBundle/Resources/views/Field/*.html.twig` and modify it. + + +How modify templates including base `text.html.twig` template +============================================================= + +Several templates including the base `text.html.twig` template. +So you will want modify it, but you also need modify templates including it - change `include` statement. + +For example `email.html.twig` including:: + + {{ include('@MauticForm/Field/text.html.twig', { ... + +you need change `@MauticForm` to you theme, for example:: + + {{ include('@themes/MyTheme/Field/text.html.twig', { ... \ No newline at end of file From 341548aa63bfc9e5d241494b9c72e01ba355c455 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Pokorn=C3=BD?= Date: Thu, 23 May 2024 22:10:46 +0200 Subject: [PATCH 28/30] fix linter - missing doctrine-project links --- docs/links/doctrine_docs_orm.py | 2 +- docs/links/doctrine_docs_orm_annotations.py | 2 +- docs/links/doctrine_docs_orm_php_mapping.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/links/doctrine_docs_orm.py b/docs/links/doctrine_docs_orm.py index cd9f2836..445c1cbf 100644 --- a/docs/links/doctrine_docs_orm.py +++ b/docs/links/doctrine_docs_orm.py @@ -2,6 +2,6 @@ link_name = "Doctrine ORM" link_text = "Doctrine ORM" -link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/index.html" +link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/index.html" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/doctrine_docs_orm_annotations.py b/docs/links/doctrine_docs_orm_annotations.py index 04bb2f44..b651b610 100644 --- a/docs/links/doctrine_docs_orm_annotations.py +++ b/docs/links/doctrine_docs_orm_annotations.py @@ -2,6 +2,6 @@ link_name = "Doctrine ORM annotations" link_text = "Doctrine ORM annotations" -link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/reference/annotations-reference.html" +link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/reference/annotations-reference.html" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/doctrine_docs_orm_php_mapping.py b/docs/links/doctrine_docs_orm_php_mapping.py index 28c14631..e2e48ead 100644 --- a/docs/links/doctrine_docs_orm_php_mapping.py +++ b/docs/links/doctrine_docs_orm_php_mapping.py @@ -2,6 +2,6 @@ link_name = "Doctrine ORM PHP mapping" link_text = "Doctrine ORM PHP mapping" -link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.9/reference/php-mapping.html#classmetadatabuilder" +link_url = "https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/reference/php-mapping.html#classmetadatabuilder" link.xref_links.update({link_name: (link_text, link_url)}) From 4f6fc17653d34f10e6362c4bfd3aa8b2501dc3ec Mon Sep 17 00:00:00 2001 From: Lukas Pokorny Date: Fri, 24 May 2024 17:21:25 +0200 Subject: [PATCH 29/30] Apply suggestions from code review Co-authored-by: John Linhart --- docs/themes/forms.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/themes/forms.rst b/docs/themes/forms.rst index 78c35fec..c8bccc0d 100644 --- a/docs/themes/forms.rst +++ b/docs/themes/forms.rst @@ -17,20 +17,19 @@ You can add a custom style sheet to the Form by adding a ``_style.html.twig`` wi Customize field types ********************* -For change HTML generated by field types, you can create a new template in the `Field` directory. -I recommend copy the original template from `app/bundles/FormBundle/Resources/views/Field/*.html.twig` and modify it. +Create a new template in the `Field` directory to change HTML generated by field types. +The best way is to copy the original template from `app/bundles/FormBundle/Resources/views/Field/*.html.twig` and modify it. -How modify templates including base `text.html.twig` template -============================================================= +How to modify templates including base `text.html.twig` template +================================================================ -Several templates including the base `text.html.twig` template. -So you will want modify it, but you also need modify templates including it - change `include` statement. +Several templates are including the base `text.html.twig` template so you may need modify it. In that case you also need to modify templates including it. Change the `include` statement. -For example `email.html.twig` including:: +For example `email.html.twig` including: {{ include('@MauticForm/Field/text.html.twig', { ... -you need change `@MauticForm` to you theme, for example:: +you need change `@MauticForm` to you theme, for example: {{ include('@themes/MyTheme/Field/text.html.twig', { ... \ No newline at end of file From d350a9b73c5039e3e3418390499a578978d37e7d Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Fri, 31 May 2024 17:13:47 +0100 Subject: [PATCH 30/30] Update .vale.ini --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index fda54427..b88c2b88 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,5 @@ StylesPath = .github/styles Vocab = Mautic -MinAlertLevel = warning +MinAlertLevel = suggestion [*.{md,rst}] BasedOnStyles = Vale, Google, Mautic