getting started  »  kettle

Kettle

The Pop PHP Framework includes kettle, a CLI-based helper script. It allows a user to quickly build the scaffolding for an application and manage database functions from the command line.

Initializing an Application

By running the following command, you can set up the basic files and folders required to run an application:

./kettle app:init [--web] [--api] [--cli] <namespace>

The <namespace> parameter is the namespace of your application, for example MyApp. The optional parameters of --web, --api, and --cli will create the related files and folders to run the application as a normal web application, an API-driven web application, a CLI-driven console application or any combination thereof. The default route for the web application or the API application is /. However, if both are initialized, then the default route for the API application becomes to /api. The web application will deliver a placeholder HTML page and the API application will deliver a placeholder JSON response.

After running the command, the basic application file and folder structure will look like:

  • app/
    • config/
    • src/
    • view/
  • database/
    • migrations/
    • seeds/
  • public/
  • script/
  • kettle
  • kettle.inc.php

The web/API application's front controller will be located in public/index.php and the main script for the CLI application will be located in script/myapp (named according to the provided <namespace> value.)

After the application files and folders are copied over, you will be asked if you would like to configure a database. Follow those steps to configure a database and create the database configuration file.

Application Status

You can view and manage the status of the application with the following commands outlined below.

Check the current environment:

The environment is set in the .env file under the APP_ENV variable. Options available are:

  • local
  • dev
  • testing
  • staging
  • production (or prod)
./kettle app:env
Check (or change) the current status:

The status of the application can either be "live" or in "maintenance mode". The value is set in the .env file under the MAINTENANCE_MODE variable (true or false).

./kettle app:status

To put the application into maintenance mode, where it's not accessible, use the following command:

./kettle app:down

You can generate a "secret" key to allow a select set of users to view the application while still in maintenance mode:

./kettle app:down --secret

When the command finishes, it will output the auto-generated secret:

The secret is SECRET_STRING

You can also provide your own secret:

./kettle app:down --secret=MY_SECRET_STRING

Use that string one time in the browser as a URL query parameter to view the application while it is still in maintenance mode. It will store in the browser's cookies so subsequent requests will be valid:

http://localhost:8000/?secret=SECRET_STRING

To take the application out of maintenance mode and make it live again, use the following command:

./kettle app:up

Kettle Include

You should see a file kettle.inc.php next to the main kettle script. This serves as a configuration file for anything additional that needs to be wired up for your application to work with kettle. The file is included right after the creation of the $autoloader and $app objects, so you will have direct access to them. In this file you can add any additional runtime requirements, configurations or routes.

For example, there may be an instance were kettle needs to be aware of your application and its namespace. You can access the autoloader here and register your application with kettle in the kettle.inc.php file:

$autoloader->addPsr4('MyApp\\', __DIR__ . '/app/src');

Note: If the kettle.inc.php file isn't available, you can copy it from the vendor/popphp/pop-kettle/kettle location to the main project folder (adjacent to the vendor folder.)

Managing Databases

Once the application is initialized, you can manage the database, or multiple databases, by using the db and migrate commands. If you don't pass anything in the optional [<database>] parameter, it will default to the default database.

./kettle db:install [<database>]
./kettle db:config [<database>]
./kettle db:test [<database>]
./kettle db:create-seed <seed> [<database>]
./kettle db:seed [<database>]
./kettle db:export [<database>]
./kettle db:import <file> [<database>]
./kettle db:reset [<database>]
./kettle db:clear [<database>]

./kettle migrate:create <class> [<database>]
./kettle migrate:run [<steps>] [<database>]
./kettle migrate:rollback [<steps>] [<database>]
./kettle migrate:point [<id>] [<database>]
./kettle migrate:reset [<database>]
Installing the Database

The command db:install a convenient combination the db:config, db:test and db:seed commands. Running the command will prompt you to enter the database configuration parameters. Once those are entered, it will test the database, and on a successful test, it will run the seed command and import any initial data it finds in the seed folder. The db:install command is what runs at the end of the app:init command if you answer Y to the question Would you like to configure a database?

Seeding the Database

You can seed the database with data in one of two ways. You can either utilize a SQL file with the extension .sql in the /database/seeds/<database> folder or you can write a seeder class using PHP. To create a seeder class, you can run:

./kettle db:create-seed <seed> [<database>]

Where the <seed> is the base class name of the seeder class that will be created. The template seeder class will be copied to the /database/seeds/<database> folder:

use Pop\Db\Adapter\AbstractAdapter;
use Pop\Db\Sql\Seeder\AbstractSeeder;

class MyFirstSeeder extends AbstractSeeder
{

    public function run(AbstractAdapter $db): void
    {

    }

}

From there, you can fill in the run() method in the seeder class with the SQL you need to seed your data:

use Pop\Db\Adapter\AbstractAdapter;
use Pop\Db\Sql\Seeder\AbstractSeeder;

class DatabaseSeeder extends AbstractSeeder
{

    public function run(AbstractAdapter $db): void
    {
        $sql = $db->createSql();

        $sql->insert('users')->values([
            'username' => 'testuser',
            'email'    => 'test@test.com'
        ]);

        $db->query($sql);
    }

}

Then running the following command will execute any SQL in the seeder classes or any raw SQL in SQL files:

./kettle db:seed
Database Migrations

You can create the initial database migration that would modify your database schema as your application grows by running the command:

./kettle migrate:create <class> [<database>]

Where the <class> is the base class name of the migration class that will be created. You will see your new migration class template in the /database/migrations/<database> folder:

use Pop\Db\Sql\Migration\AbstractMigration;

class MyFirstMigration5dd822cdede29 extends AbstractMigration
{

    public function up(): void
    {

    }

    public function down(): void
    {

    }

}

From there, you can populate the up() and down() with the schema to modify your database:

use Pop\Db\Sql\Migration\AbstractMigration;

class MyFirstMigration5dd822cdede29 extends AbstractMigration
{

    public function up(): void
    {
        $schema = $this->db->createSchema();
        $schema->create('users')
            ->int('id', 16)->increment()
            ->varchar('username', 255)
            ->varchar('password', 255)
            ->varchar('email', 255)
            ->primary('id');

        $schema->execute();
    }

    public function down(): void
    {
        $schema = $this->db->createSchema();
        $schema->drop('users');
        $schema->execute();
    }

}

You can run the migration and create the users table by running the command:

./kettle migrate:run

And you can rollback the migration and drop the users table by running the command:

./kettle migrate:rollback
Migration State Storage

The migration state storage can be stored in one of two places. By default, it will store in a file called .current in the database migration folder, for example:

/database/migrations/default/.current

However, it can also be stored in the database itself in a separate migrations table. This requires a file called .table to be placed in the database migration folder:

/database/migrations/default/.table

The contents of the table will be the table class name for the migrations table in the database. This relies on the Pop\Db\Record class in the pop-db component. For more about that, refer to Databases section of the user guide.

MyApp\Table\Migrations

Please note, while kettle is a CLI-helper tool that assists in wiring up your initial application, it is unaware of your application and its namespace. If you choose to manage database migrations with a database table, kettle will have to be made aware of the namespace and location of your application. You can do that by adding it to the autoloader in the kettle.inc.php file:

$autoloader->addPsr4('MyApp\\', __DIR__ . '/app/src');

Creating App Files

You can create skeleton application files with the create commands to assist you in wiring up various MVC-based components, such as models, views and controllers:

./kettle create:ctrl [--web] [--api] [--cli] <ctrl>
./kettle create:model [-d|--data] <model>
./kettle create:view <view>

Once the respective class files or view scripts are created in the appropriate folders, you can then open them up and begin writing your application code.

Data Model

The --data option for the create:model command creates a model class that extends the Pop\Model\AbstractDataModel class, as well as a table class to interface with the corresponding table in the database. For example, assuming the namespace of the applicaton is MyApp, the command:

./kettle create:model --data User

will create class files for MyApp\Model\User and MyApp\Table\Users. From there, using the model class, you can begin to store and retrieve data from the users table in the database with very little additional coding.

Web Server

pop-kettle also provides a simple way to run PHP's built-in web-server, by running the command:

./kettle serve [--host=] [--port=] [--folder=]

This is for development environments only and it is strongly advised against using the built-in web server in a production environment in any way.

Accessing the App

If you have wired up the beginnings of an application, you can then access the default routes in the following ways. Assuming you've started the web server as described above using ./kettle serve, you can access the web application by going to the address http://localhost:8000/ in any web browser and seeing the default index HTML page.

If you want to access the API application, the default route for that is http://localhost:8000/api and you can access it like this to see the default JSON response:

curl -i -X GET http://localhost:8000/api

And, if you cd script, you'll see the default CLI application that was created. The default route available to the CLI application is the help route:

./myapp help

Shell Completion

Shell completion for both bash and zsh shells is available. Simply copy the correct shell completion file to your user home directory and add them via the source command to your shell's read command file.

BASH
cp .kettle.bash ~/

Edit the ~/.bashrc file and add this:

source ~/.kettle.bash
ZSH
cp .kettle.zsh ~/

Edit the ~/.zshrc file and add this:

source ~/.kettle.zsh

Once you've set up your preferred shell, close all terminal windows and re-open a new one. Change directory to any project that has the kettle script in it and the auto-completion should now be available.

Windows

Most UNIX-based environments should recognize the main kettle application script as a PHP script and run it accordingly, without having to explicitly call the php command and pass the script and its parameters into it. However, if you're on an environment like Windows, depending on your exact environment set up, you will most likely have to prepend all of the command calls with the php command, for example:

C:\popphp\pop-kettle>php kettle help