Forem: Arman

What’s New in Quantum PHP Framework 2.9 Release

Arman — Sat, 11 Jan 2025 10:39:28 +0000

The Quantum PHP Framework team has wrapped up 2024 with an exciting new release — version 2.9, which debuted at the end of November. This update, arriving just under a year after the 2.8 release, brings a fresh wave of enhancements and features, reinforcing Quantum’s position as a robust and developer-friendly framework.

Version 2.9 introduces a powerful set of tools designed to simplify and elevate web development. Highlights include a new CAPTCHA library to bolster security, an Archive library for seamless file compression, and significant updates to the Mailer library, enhancing email handling. The Filesystem library now supports a Google Drive adapter, making cloud storage integration effortless. Developers can also look forward to a new Module generation command, streamlining the creation of modular applications, and an all-new pagination feature for improved data navigation.

Let’s dive into the details of these features and explore how they can benefit your next project!

Enhanced Security with the New CAPTCHA Library

The Quantum PHP Framework 2.9 introduces a new CAPTCHA library, empowering developers to integrate advanced security mechanisms into their applications. With support for two of the most popular CAPTCHA services reCAPTCHA ** and **hCaptcha. This library offers robust protection against bots and automated abuse. The library supports both visible CAPTCHAs, where users interact directly with security challenges, and invisible CAPTCHAs, which work silently in the background to verify users without disrupting their experience.

To begin, add the necessary CAPTCHA keys to your .env file:

RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=

HCAPTCHA_SITE_KEY=
HCAPTCHA_SECRET_KEY=

In the shared/config/captcha.php configuration file, specify the desired adapter (reCAPTCHA or hCaptcha) and set its type (visible or invisible). Here's an example configuration:

return [
    /**
     * ---------------------------------------------------------
     * Captcha configurations
     * ---------------------------------------------------------
     */
    'current' => 'recaptcha', // Set to 'recaptcha' or 'hcaptcha'

    'recaptcha' => [
        'type' => 'visible', // Options: 'visible' or 'invisible'
        'site_key' => env('RECAPTCHA_SITE_KEY'),
        'secret_key' => env('RECAPTCHA_SECRET_KEY'),
    ],

    'hcaptcha' => [
        'type' => 'invisible',
        'site_key' => env('HCAPTCHA_SITE_KEY'),
        'secret_key' => env('HCAPTCHA_SECRET_KEY'),
    ],
];

In your view file (e.g., the signup page), integrate the CAPTCHA widget into your form using the helper function:

echo captcha()->addToForm('signUpForm', ['class' => 'col s1 offset-s4']);

$formIdentifier: A string parameter required for invisible CAPTCHA. It binds the CAPTCHA to the specified form.
$attributes: An array parameter used for visible CAPTCHA, allowing you to define custom tag attributes.

To verify the CAPTCHA response, either create new middleware or update an existing one. For example, in the modules/Web/Middlewares/Signup.php middleware, you can add the validation rule alongside other rules:

$this->validator->addRules([
    // Other validation rules...
    'captcha' => [
        Rule::set('required'),
        Rule::set('captcha'),
    ],
]);

Simplify File Compression with the New Archive Library

Quantum PHP Framework 2.9 introduces a robust Archive library, making file compression and extraction more straightforward than ever. This library provides two versatile adapters — Zip and Phar.

Creating a Zip Archive:

use Quantum\Libraries\Archive\Adapters\ZipAdapter;


$zip = new ZipAdapter('my-archive.zip');

$zip->addFile('path/to/file1.txt', 'documents/file1.txt');
$zip->addFile('path/to/image.jpg', 'images/image.jpg');

Extracting Files from a Zip Archive:

use Quantum\Libraries\Archive\Adapters\ZipAdapter;

$zip = new ZipAdapter('my-archive.zip');

$zip->extractTo('path/to/extract/directory');

You can add multiple files to archive:

$zip->addMultipleFiles([
    ['path' => 'path/to/source/file1.txt', 'name' => 'file1.txt'],
    ['path' => 'path/to/source/file2.txt', 'name' => 'file2.txt'],
]);

And even add files from string:

$zip->addFromString('sample.txt', 'Just a sample text');

There are many more helpful methods available and same applies for PharAdapter.

Mailer Library: Flexible Email Integration with Multiple Adapters

The Mailer library in Quantum PHP Framework 2.9 introduces a robust and flexible email delivery system that supports multiple adapters, allowing you to integrate various email services with ease. Whether you need to send emails via a local SMTP server or use cloud-based email services, this library provides all the necessary tools to get started.

SMTP: For sending emails via a local or remote SMTP server.
Mailgun: For sending emails through Mailgun’s email API.
Mandrill: For sending emails through Mandrill’s email delivery service.
SendGrid: For using SendGrid’s email API to send emails.
SendinBlue: For leveraging SendinBlue’s SMTP and email API.

Setting Up the Mailer:

To begin, add the corresponding values to the .env file. If you're using SMTP, you'll need to provide the following settings:

MAIL_HOST=
MAIL_SMTP_SECURE=
MAIL_PORT=
MAIL_USERNAME=
MAIL_PASSWORD=

Next, in the shared/config/mailer.php file, make sure to specify the current adapter in use. Here's an example of how to set it up:

return [
    /**
     * ---------------------------------------------------------
     * Mailer Settings
     * ---------------------------------------------------------
     *
     * Set the current configuration to use.
     */
    'current' => 'smtp',  // Set the adapter in use

    'smtp' => [
        'host' => env('MAIL_HOST'),
        'secure' => env('MAIL_SMTP_SECURE'),
        'port' => env('MAIL_PORT'),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
    ],

    'sendinblue' => [
        'api_key' => env("SENDINBLUE_APIKEY", null),
    ],

    'sendgrid' => [
        'api_key' => env("SENDGRID_APIKEY", null),
    ],

    'mailgun' => [
        'api_key' => env("MAILGUN_APIKEY", null),
        'domain' => env("MAILGUN_DOMAIN", null),
    ],

    'mandrill' => [
        'api_key' => env("MANDRILL_APIKEY", null),
    ],
];

Once all the configurations are set, you can use the mailer() helper method to compose and send emails. Here's an example:

mailer()
    ->setFrom('johndoe@mail.com', 'John Doe')  
    ->setAddress('ban@mail.com', 'Ban Doe')   
    ->setSubject('Hello')                     
    ->setBody('Hello everyone')                
    ->send();

FileSystem Library: Google Drive Adapter

The FileSystem library in Quantum PHP now includes a new GoogleDrive adapter, alongside the previously available Local and Dropbox adapters. This new adapter allows you to manage files directly on your Google Drive, offering additional flexibility for file storage.

To use the Local Filesystem adapter, simply create a new instance of FileSystem(). By default, this will utilize the LocalFileSystemAdapter.

For Dropbox or Google Drive, additional setup is required.

To work with Google Drive, you need to pass the GoogleDriveFileSystemAdapter as an argument to the FileSystem() constructor. The GoogleDriveFileSystemAdapter requires an instance of GoogleDriveApp which handles essential tasks such as making HTTP requests, managing tokens, and more (Similarly, when using the DropboxFileSystemAdapter, you'll need to provide a DropboxApp instance).

Since token management is the developer’s responsibility, you must also implement the TokenServiceInterface to handle token-related operations seamlessly.

The TokenServiceInterface requires the implementation of the following three methods:

namespace Quantum\Libraries\Storage\Adapters\Dropbox;

interface TokenServiceInterface
{
    public function getAccessToken(): string;

    public function getRefreshToken(): string;

    public function saveTokens(string $accessToken, ?string $refreshToken = null): bool;
}

To manage access and refresh tokens, you need to create a TokenService class that implements the TokenServiceInterface. This class should be implemented to align with the specific requirements of the application, ensuring proper storage and retrieval of tokens.

Once your TokenService class is ready, it should be passed to the GoogleDriveApp, which will use it to manage token operations effectively. The oogleDriveApp relies on this service for obtaining access tokens, refreshing them, and saving updated tokens when needed.

use Quantum\Libraries\Storage\Adapters\GoogleDriveFileSystemAdapter;
use Quantum\Libraries\Storage\Adapters\GoogleDriveApp;
use Quantum\Libraries\Storage\FileSystem;
use Quantum\Libraries\Curl\HttpClient;
use Shared\Services\TokenService;

$appKey = config()->get('filesystem.gdrive.appKey');
$appSecret = config()->get('filesystem.gdrive.appSecret');

$httpClient = new HttpClient();

$tokenService = new TokenService();

$googleDriveApp = new GoogleDriveApp($appKey, $appSecret, $tokenService, $httpClient);

$googleDriveAdapter = GoogleDriveFileSystemAdapter::getInstance($googleDriveApp);

$fileSystem = new FileSystem($googleDriveAdapter);

Once the GoogleDrive adapter is set up, you can call any available method to interact with files as usual:

// Upload a file
$fileSystem->put('folder/file.txt', 'This is the file content');

// Retrieve a file's content
$content = $fileSystem->get('folder/file.txt');

// Delete a file
$fileSystem->delete('folder/file.txt');

While we’ve explored many aspects of the library in this article, some features, like Module Generation and Pagination, deserve their own deep dives. These are significant features with substantial functionality that require more detailed explanation. Stay tuned, as we’ll provide separate articles on these topics in the near future to help you fully leverage their potential.

To get started or explore more, visit the Quantum PHP Core GitHub repository for the source code or check out the official Quantum PHP website for detailed documentation and resources.

We encourage you to explore Quantum PHP Core’s capabilities and see how it can simplify your development journey. Happy coding!

Database Migrations

Arman — Mon, 04 Jul 2022 14:09:38 +0000

Suppose we are starting a new big project and of course first thing to do is to compose our database architecture. And we want to use some sort of relational database system such as MySQL.

Surely we can go ahead and create our database and the tables through some GUI or via terminal. And then we can start codding our project business logic. If on the project works more people than us, then we should share our DB schema with other developers. We can do it by exporting the SQL dump and sending to them to import.

Sounds good so far…

Now suppose some developers are adding new columns on some of the tables on their branch. Other developers are removing some columns (as per requirement of their task). Some other developers may change some columns (like changing type or names or indexes, etc.).

This quickly becomes a mess, as nobody can tell exactly which operations should be taken in the first place, which are in the second and so on…

Migrations comes to help

Database migrations or simply migrations, are controlled sets of changes developed to modify the structure of the objects within a relational database. Migrations help transition database schemas from their current state to a new desired state. Whether that involves adding tables and columns, removing elements, splitting fields, or changing types and constraints.

The goals of database migrations are to make database changes repeatable, shareable, and testable.
In general, migration systems create files that can be shared, applied to multiple database systems, and stored in version control.

Migrations in Quantum framework

From version 2.7.0 Quantum comes with new migration feature which allows developers to fill that gap they have previously. It currently supports MySQL 8 and above as well as Mariadb 10.5.x and above. In near future it’s expected to have SQLIte and PostgreSQL included. The way of creating and applying migrations, are done via console commands and it mostly similar to other PHP frameworks if you tried one already.

The first thing to do is to generate a migration file. which can be done via migration:generate command. The command accepts arguments, "type" and "table name". There are 4 types available for generating migrations, create, alter, rename and drop.

Create table migration

To generate create type of migration we specify the type as first parameter and the table name as second.

> php qt migration:generate create users

The new migration file will be created in the project migrations directory and will named something like create_table_users_1655307916.php with some prefilled content.

<?php 
use Quantum\Migration\QtMigration; 
use Quantum\Factory\TableFactory; 
use Quantum\Libraries\Database\Schema\Type; 
use Quantum\Libraries\Database\Schema\Key; 
class Create_table_users_1655307916 extends QtMigration 
{ 
    public function up(?TableFactory $tableFactory) 
    {
        $table = $tableFactory->create('users'); 
    } 
    public function down(?TableFactory $tableFactory) 
    { 
        $tableFactory->drop('users'); 
    } 
}

Alter table migration

To generate alter type of migration we specify the type as first parameter and the table name as second.

> php qt migration:generate alter users

The new migration file will be created in the project migrations directory and will named something like alter_table_users_1655308339.php with some prefilled content

<?php 
use Quantum\Migration\QtMigration; 
use Quantum\Factory\TableFactory; 
use Quantum\Libraries\Database\Schema\Type; 
use Quantum\Libraries\Database\Schema\Key; 
class Alter_table_users_1655308339 extends QtMigration 
{ 
    public function up(?TableFactory $tableFactory) 
    { 
        $table = $tableFactory->get('users'); 
    } 
    public function down(?TableFactory $tableFactory) 
    { 
        $table = $tableFactory->get('users'); 
    } 
}

Rename table migration

To generate rename type of migration we specify the type as first parameter and the table name as second.

> php qt migration:generate rename users

The new migration file will be created in the project migrations directory and will named something like rename_table_users_1655308655.php with some prefilled content.

Notice, that the new table name need to be added there as a 2nd argument of rename() method.

<?php 
use Quantum\Migration\QtMigration;  
use Quantum\Factory\TableFactory; 
class Rename_table_users_1655308655 extends QtMigration 
{ 
    public function up(?TableFactory $tableFactory) 
    { 
        $tableFactory->rename('users', $newName); 
    } 
    public function down(?TableFactory $tableFactory) 
    { 
        $tableFactory->rename($newName, 'users'); 
    } 
}

Drop table migration

To generate drop type of migration we specify the type as first parameter and the table name as second.

> php qt migration:generate drop users

The new migration file will be created in the project migrations directory and will named something like drop_table_users_1655308866.php with some prefilled content

<?php 
use Quantum\Migration\QtMigration; 
use Quantum\Factory\TableFactory; 
class Drop_table_users_1655308866 extends QtMigration 
{ 
    public function up(?TableFactory $tableFactory) 
    { 
        $tableFactory->drop('users'); 
    } 
    public function down(?TableFactory $tableFactory) 
    { 
        // 
    } 
}

As we can see, every time it creates a class which extends the QTMigration base class and it always has 2 public methods: up() and down().

The up method is used to create new tables, columns, or indexes to your database, while the down method should reverse the operations performed by the up method.

Updating migration file content

Ok, now let’s open our migration file and add some new columns to the table with addColumn() method..

public function up(?TableFactory $tableFactory) 
{ 
    $table = $tableFactory->create('users'); 
    $table->addColumn('id', Type::INT, 11)->autoIncrement(); 
    $table->addColumn('username', Type::VARCHAR, 100)->unique(); 
    $table->addColumn('is_active', Type::BOOL); 
    $table->addColumn('options', Type::ENUM, ['op1', 'op2', 'op3'])->default('op2'); 
}

We have added 3 columns to the table:

id as integer with autoincrement
username as varchar with unique index
options as enum with default value
We can also alter the existing column paramters with modifyColumn() method.

public function up(?TableFactory $tableFactory) 
{ 
    $table = $tableFactory->get('users'); 
    $table->modifyColumn('username', Type::VARCHAR, 50); 
    $table->modifyColumn('is_active', Type::TINYINT, 1); 
}

Here we have modified 2 columns:

username column length was changed from 100 to 50
is_active column type was changed from boolean to tinyint
We can also rename columns with renameColumn() method.

public function up(?TableFactory $tableFactory) 
{ 
    $table = $tableFactory->get('users'); 
    $table->renameColumn('username', 'email'); 
}

To drop columns we use dropColumn() method.

public function up(?TableFactory $tableFactory) 
{ 
    $table = $tableFactory->get('users'); 
    $table->dropColumn('options'); 
}

Playing with indexes

When adding new column we can also specify the index with it as well, like:

$table->addColumn('profile_id', Type::INT, 11)->index();

Also we can specify the index name:

$table->addColumn('profile_id', Type::INT, 11)
      ->index('idx_profile_id');

There are 5 types of indexes are available: primary, index, unique, fulltext and spatial.

In order to add index key to an existing column we can use addIndex() method like:

$table->addIndex('profile_id', Key::INDEX);

Or with the index name:

$table->addIndex('profile_id', Key::INDEX, 'idx_profile_id');

Remember, if you are not specifying the index name, it will take the column name is its key name.

To drop the index from the column we can use dropIndex() method by passing the index name as paramter like this:

$table->dropIndex('idx_profile_id');

Migrating migrations

Ok, now when we have our table schemas defined in the migration files, it’s time to migrate them.

So to apply the migrations we simply run this command (the argument up is optional and can be skipped):

> php qt migration:migrate up

If you running this command first time, it will create new table in your database with name migrations, where it will store all applied migrations. Then it will iterate through the migrations which were created and run them all in chronological order.

Notice that the migration:migrate command runs only up migrations and only ones that weren't yet migrated.

If you want to roll back the migrated migrations you will need to run:

> php qt migration:migrate down

Be aware that this will iterate through all the migrations in reverse chronological order and run down migrations. If you want to roll back not all the migrations but down to specific migration, you can specify the step:

> php qt migration:migrate down --step=2

This is all for today, hope you find it useful, write comments if you have questions… Good luck.