Download the PHP package bytespin/console-command-scheduler-bundle without Composer

Copyright (c) 2023 Greg LAMY [email protected]

This is a public project hosted on GitHub : https://github.com/ByteSpin/ConsoleCommandSchedulerBundle.git

This bundle was originally developed as part of an ETL project.

ByteSpin/ConsoleCommandSchedulerBundle is a Symfony 6.3 simple bundle that allows you to schedule console commands easily:

• Use the latest messenger/scheduler Symfony 6.3+ components,
• Log all console commands data (last execution time, duration, return code) in database and log file,
• An admin interface is available with the help of EasyCorp/EasyAdmin bundle
• Specific events are available for deeper integration with your application and/or notification system
• An extendable notification system (by email)

[!NOTE]

This project is still at beta state.

Feel free to submit bug and/or pull requests!

You can check the CHANGELOG to see the latest improvements and fixes.

Just keep in mind that I want to keep it as simple as possible!

[!IMPORTANT]

Version 1.0.13 requires schema update. Please run :

Requirements

• php 8.2+
• Symfony 6.3+

Installation

1. First install the bundle:

2. Then update the database schema:

Updating the bundle

For now, the bundle still lacks a custom recipe to manage database schema upgrade when needed.

Do not forget to update the database schema when updating the bundle

The last version that includes schema modifications is : 1.0.13

Manual bundle registration

You will need to manually register the bundle in your application.

To do this, follow these steps:

1. Open the file config/bundles.php in your Symfony application.

2. Add the following line to the array returned by this file:

3. Save the file. Your bundle is now registered and ready to be used in your application.

Make sure to perform this step after you have installed the bundle using Composer, but before you use any of its features in your application.

Configuration

You will have to configure the entity manager to be used with the ByteSpin\ConsoleCommandSchedulerBundle entities. This has to be done once after installation. We provide a script to automatise this step ; please run :

If you prefer to do this by yourself, add the following lines just within your entity manager 'mappings:' key in doctrine.yaml :

[!IMPORTANT]

If your project contains entities mapped to multiple entity managers, be careful to not use the auto_mapping: true in your doctrine configuration.

This would prevent the getManagerForClass() function used in the bundle to get the correct entity manager to work properly!

In such case :

• Choose the correct entity manager when you run the configuration script,
• Be sure to remove the 'auto_mapping: true' key from your doctrine.yaml (or set it to false),
• Be sure that ALL your entities are correctly mapped in the 'mappings:' sections of your doctrine.yaml

Administration interface

[!NOTE]

Please note that the administration interface is based on EasyAdmin symfony bundle.

Because you might already use EasyAdmin in your project, no DashboardController is provided with the bundle.

If you don't have one, generate it with

You need to manually add the menu to your DashboardController.php file, for example:

(The previous lines make use of FontAwesome icons. You are free to use any other solution)

Usage

[!NOTE] The bundle makes use of the very new symfony/scheduler component that is said to be experimental on 6.3 symfony version

That will change in the forthcoming 6.4 release.

The only documentation available for the moment is on the official symfony blog, with some useful examples. Please read it carefully at https://symfony.com/blog/new-in-symfony-6-3-scheduler-component

The 'from_date', 'from_time', 'until_date', 'until_time' bundle parameters are used to construct the expected scheduler trigger

The administration interface provides two sections:

• The main console command scheduler section:

  • When you click on the menu, EasyAdmin provides the default list view for Console Commands Scheduler

  • You can add/view/edit any entry in this list:

    • Disabled: if checked, the Console Command will be ignored by the scheduler
    • Command: this field lists all available console commands defined in your symfony project
    • Arguments: provide any console command arguments if needed, separated by a space, as if you were typing them on the command line
    • Type: here you select one of the two symfony/scheduler supported command type
      • 'Frequency' will generate a trigger of the RecurringMessage::every form,
      • 'Cron' = will generate a trigger of the RecurringMessage::cron form
    • Frequency: here you type the desired frequency
      • If Type is 'Frequency' ; for example '10 seconds', '1 day', 'first monday of next month' (refer to the doc)
      • If Type is 'Cron' ; use any cron expression
    • From Date, From Time, Until Date, Until Time are used to generate the trigger. They are ignored in case of 'Cron' Type.
    • Log File: you can provide the log file name desired for the current command.
      • Please note that you must not provide the full path, only the log filename.
      • If not provided, a default %env%_scheduler.log is created.
    • No DB Log: Enabling this option ensures that no logs related to this event are recorded in the database. However, standard logging to files will continue as usual. This feature is useful for reducing database clutter or when database logging is not required for specific events.

• The log section: provides a simple log viewing interface

Consuming messages

The standard way of consuming scheduler messages is

If you want the command to be verbose, please use:

You can use cron or supervisor to achieve this ; The console commands are then executed according to the generated triggers.

The commands returning code, date and duration are logged in the dedicated table and in a dedicated log

You can view the logs in the administration interface

Events

New generic events are now dispatched by the bundle for deeper integration with your application and/or a notification system:

• bytespin.before.scheduled.console.command: event is dispatched just before console command execution
• bytespin.success.scheduled.console.command: event is dispatched in case of console command success (return code == 0)
• bytespin.failure.scheduled.console.command: event is dispatched in case of console command failure (return code != 0)
• bytespin.after.scheduled.console.command: event is dispatched just after console command execution

The event subject is normalized and contains all console command useful data.

Use ByteSpin events through an event subscriber with a simple mail notification example:

Notification system

A new notification system is now provided by the bundle that can be extended in your own console commands.

First, you will have to add a new environment variable in your project .env file: [email protected] Provide a valid mail from address. Do not forget to configure the mailer dsn in you project.

• The administration interface (easyadmin) now provides 3 more fields:

  • send notification (bool)
  • notification email (varchar)
  • job title (varchar - it will override command name and parameters in the notification email)
• When notification is enabled and valid email address provided:
  • a notification email will be sent at the end of console command execution
  • the notification email will provide some details about your command execution (duration, return code, command, arguments etc.)

The bundle natively only send details about the main console command scheduled by the bundle. In some cases, your command can run several sub-steps for which you may need more details in notification. For this, the bundle provides a new event you can dispatch in your commands

That's it, you will get detailed notification in your mailbox!

Licence

This project is licensed under the MIT License - see the LICENSE file for details.