Download the PHP package popphp/pop-kettle without Composer

pop-kettle

• Overview
• Install
• Initializing an Application
  • Application Status
• Kettle Include
• Managing the Database
  • Seeding the Database
  • Database Migrations
  • Migration State Storage
• Creating Application Files
  • Data Model
• Running the Web Server
• Accessing the Application
• Shell Completion
• Using on Windows

Overview

pop-kettle is a CLI-helper application for the Pop PHP Framework that allows a user to quickly build the scaffolding for an application. It is included with the Pop PHP Framework as the command kettle within the main project directory.

Top

Install

The pop-kettle component comes automatically installed when you install the full Pop PHP Framework. You should see the kettle script in the main project directory. However, if that is not the case, and you need to install it manually, you can place a copy of the kettle script from the vendor/popphp/pop-kettle/kettle location in the main project folder (adjacent to the vendor folder):

Once you've copied the script over, you have to change the reference to the script's config file from:

to

and make sure the newly copied kettle script is set to execute (755)

Top

Initializing an Application

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

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 /api. The web application will deliver a placeholder HTML page and the API application will deliver a placeholder JSON response.

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)

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).

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

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

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

You can also provide your own secret:

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:

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

Top

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:

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.)

Top

Managing the Database

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.

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:

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:

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

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

Database Migrations

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

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:

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

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

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

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:

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:

The contents of the table will be the table class name for the migrations table in the database, for example:

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:

Reference Kettle Include for more information.

Top

Creating Application 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:

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:

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.

Top

Running the Web Server

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

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.

Top

Accessing the Application

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 create both a web and API application, the HTML application will be accessible at http://localhost:8000/. 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:

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:

Top

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

Edit the ~/.bashrc file and add this:

ZSH

Edit the ~/.zshrc file and add this:

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.

Top

Using on 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: