Combustor
![Software License][ico-license]
![Coverage Status][ico-coverage]
, (*1)
Combustor is a utility package for Codeigniter 3 that generates controllers, models, and views based on the provided database tables. It uses the Describe package for getting columns from a database table and as the basis for code generation., (*2)
Features
- Generates code based on the structure of the
Codeigniter 3 framework;
- Speeds up the code development for prototyping web applications;
- View templates can be based on Bootstrap and are upgradable; and
- Only worry on the database schema, and
Combustor will do the rest.
Installation
Extract the contents of the latest Codeigniter 3 project first:, (*3)
``` bash
$ wget https://github.com/bcit-ci/CodeIgniter/archive/3.1.13.zip
$ unzip 3.1.13.zip -d ciacme, (*4)
Then configure the project's database connectivity settings:
$ cd ciacme
$ nano application/config/database.php, (*5)
``` php
// ciacme/application/config/database.php
// ...
$db['default'] = array(
'dsn' => '',
'hostname' => 'localhost',
'username' => '',
'password' => '',
'database' => '',
'dbdriver' => 'mysqli',
// ...
);
Next is to proceed in installing Combustor via Composer:, (*6)
``` bash
$ composer require rougin/combustor --dev, (*7)
``` json
// ciacme/composer.json
{
// ...
"require-dev":
{
"mikey179/vfsstream": "1.6.*",
"phpunit/phpunit": "4.* || 5.* || 9.*",
"rougin/combustor": "~1.0"
}
}
Lastly, install the ORM wrappers like Wildfire or Doctrine:, (*8)
``` bash
$ vendor/bin/combustor install:wildfire
$ vendor/bin/combustor install:doctrine, (*9)
> [!NOTE]
> Using the `install:wildfire` command installs the [Wildfire](https://roug.in/wildfire/) package while the `install:doctrine` installs the [Credo](https://roug.in/credo/) package.
## Reminders
Prior in executing any commands, kindly ensure that the _**database tables are defined properly**_ (foreign keys, indexes, relationships, normalizations) in order to minimize the modifications after the code structure has been generated.
Also, please proceed first in generating models, views, or controllers to database tables that are having _**no relationship with other tables**_ in the database.
> [!TIP]
> `Combustor` will generate controllers, models, or views based on the specified database schema. If there's something wrong in the specified database schema, `Combustor` will generate a bad codebase.
## Commands
### `create:layout`
Create a new header and footer file.
**Options**
* `--bootstrap` - adds styling based on Bootstrap
* `--force` - generates file/s even they already exists
**Example**
``` bash
$ vendor/bin/combustor create-layout --bootstrap
create:controller
Create a new HTTP controller., (*10)
Arguments, (*11)
-
table - name of the database table
Options, (*12)
-
--doctrine - generates a Doctrine-based controller
-
--wildfire - generates a Wildfire-based controller
-
--empty - generates an empty HTTP controller
-
--force - generates file/s even they already exists
[!NOTE]
If either Wildfire or Doctrine is installed, no need to specify it as option for executing a specified command (e.g. --wildfire). However if both are installed, a command must have a --wildfire or --doctrine option added., (*13)
Example, (*14)
``` bash
$ vendor/bin/combustor create:controller users --wildfire, (*15)
### `create:model`
Create a new model.
**Arguments**
* `table` - name of the database table
**Options**
* `--doctrine` - generates a Doctrine-based model
* `--wildfire` - generates a Wildfire-based model
* `--empty` - generates an empty model
* `--force` - generates file/s even they already exists
**Example**
``` bash
$ vendor/bin/combustor create:model users --wildfire
create:repository
Create a new entity repository., (*16)
Arguments, (*17)
-
table - name of the database table
Options, (*18)
-
--force - generates file/s even they already exists
Example, (*19)
``` bash
$ vendor/bin/combustor create:repository users, (*20)
> [!NOTE]
> This command is only applicable to a [Doctrine](https://roug.in/credo) implementation.
### `create:view`
Create view templates.
**Arguments**
* `table` - name of the database table
**Options**
* `--bootstrap` - adds styling based on Bootstrap
* `--doctrine` - generates Doctrine-based views
* `--wildfire` - generates Wildfire-based views
* `--force` - generates file/s even they already exists
**Example**
``` bash
$ vendor/bin/combustor create:view users --bootstrap
create:scaffold
Create a new HTTP controller, model, and view templates., (*21)
Arguments, (*22)
-
table - name of the database table
Options, (*23)
-
--bootstrap - adds styling based on Bootstrap
-
--doctrine - generates a Doctrine-based controller, model, and views
-
--wildfire - generates a Wildfire-based controller, model, and views
-
--force - generates file/s even they already exists
Example, (*24)
``` bash
$ vendor/bin/combustor create:scaffold users --bootstrap --wildfire, (*25)
> [!NOTE]
> If `--doctrine` is selected, the command will also execute the `create:repository` command.
### `install:doctrine`
Install the [Doctrine](https://roug.in/credo/) package.
**Example**
``` bash
$ vendor/bin/combustor install:doctrine
[!NOTE]
* This command will be available if Doctrine is not installed in the project.
* It also adds a Loader.php in the core directory. The said file is used for loading custom repositories extended to EntityRepository., (*26)
install:wildfire
Install the Wildfire package., (*27)
Example, (*28)
``` bash
$ vendor/bin/combustor install:wildfire, (*29)
> [!NOTE]
> This command will be available if `Wildfire` is not installed in the project.
### `remove:doctrine`
Remove the [Doctrine](https://roug.in/credo/) package.
**Example**
``` bash
$ vendor/bin/combustor remove:doctrine
[!NOTE]
This command will be available if Doctrine is installed in the project., (*30)
remove:wildfire
Remove the Wildfire package., (*31)
Example, (*32)
``` bash
$ vendor/bin/combustor remove:wildfire, (*33)
> [!NOTE]
> This command will be available if `Wildfire` is installed in the project.
## Using `combustor.yml`
`Combustor` currently works out of the box after the configuration based on `Installation`. However, using a `combustor.yml` can be used for complex setups like specifying the new application path and excluding columns:
``` yaml
# combustor.yml
app_path: %%CURRENT_DIRECTORY%%/Sample
excluded_fields:
- created_at
- updated_at
- deleted_at
To create a combustor.yml, simply run the initialize command:, (*34)
``` bash
$ vendor/bin/combustor initialize
[PASS] "combustor.yml" added successfully!, (*35)
### `app_path`
This property specifies the `application` directory. It may updated to any directory (e.g., `ciacme/application`, `ciacme/config`, etc.) as long it can detect the `config/config.php` file from the defined directory:
``` yaml
# combustor.yml
app_path: %%CURRENT_DIRECTORY%%/Sample
# ...
[!NOTE]
Combustor will try to check the path specified in app_path if it is a valid Codeigniter 3 project. Then it will perform another check if the application directory exists or if the config directory can be accessed directly from the directory defined in app_path., (*36)
excluded_fields
Specified fields in this property are excluded from generation to the following templates:, (*37)
controllersmodels-
views (only for create and edit templates)
``` yaml, (*38)
combustor.yml
...
excluded_fields:
- created_at
- updated_at
- deleted_at, (*39)
> [!NOTE]
> The timestamps are added by default when creating a `combustor.yml` for the first time as they are usually populated automatically by installed ORMs such as `Wildfire` or `Doctrine`.
### `custom_fields`
By default, all of the fields generated by `Combustor` to `create` and `edit` pages will use the `form_input` helper:
``` php
<div class="mb-3">
<?= form_label('Email', '', ['class' => 'form-label mb-0']) ?>
<?= form_input('email', set_value('email'), 'class="form-control"') ?>
<?= form_error('email', '<div><span class="text-danger small">', '</span></div>') ?>
</div>
However, some fields like email and boolean types may need to use other form helpers:, (*40)
``` php
, (*41)
= form_label('Email', '', ['class' => 'form-label mb-0']) ?>
// Still using form_input, but the type is "email" instead
= form_input(['type' => 'email', 'name' => 'email', 'value' => set_value('email'), 'class' => 'form-control']) ?>
= form_error('email', '
', '
') ?>
``` php
<div class="mb-3">
<?= form_label('Admin', '', ['class' => 'form-label mb-0']) ?>
// Use "form_checkbox" for boolean-based data types
<div>
<?= form_checkbox('admin', true, set_value('admin'), 'class="form-check-input"') ?>
</div>
<?= form_error('admin', '<div><span class="text-danger small">', '</span></div>') ?>
</div>
To achieve this, Combustor provides a utility for handling specified field names or data types using custom_fields:, (*42)
``` yaml, (*43)
combustor.yml
...
custom_fields:
- Rougin\Combustor\Template\Fields\BooleanField, (*44)
When adding a custom field, kindly create a class that extends to the `Colfield` class:
``` php
namespace Acme\Fields;
use Rougin\Combustor\Colfield;
class EmailField extends Colfield
{
protected $class = 'form-control';
/**
* If $name is specified, it will check if the current field
* name matches the in this $name field.
*/
protected $name = 'email';
public function getPlate()
{
$field = $this->accessor;
$class = $this->getClass();
/** @var string */
$name = $this->getName();
$html = '<?= form_input([\'type\' => \'email\', \'name\' => \'' . $name . '\', \'value\' => set_value(\'' . $name . '\')]) ?>';
if ($this->edit)
{
$html = str_replace('set_value(\'' . $name . '\')', 'set_value(\'' . $name . '\', ' . $field . ')', $html);
}
$html = str_replace(')]) ?>', '), \'class\' => \'' . $class . '\']) ?>', $html);
return array($html);
}
}
Then after creating the custom field, simply add the class name to the combustor.yml:, (*45)
``` yaml, (*46)
combustor.yml
...
custom_fields:
- Rougin\Combustor\Template\Fields\BooleanField
- Acme\Fields\EmailField, (*47)
## Changelog
Please see [CHANGELOG][link-changelog] for more information what has changed recently.
## Testing
``` bash
$ composer test
Credits
License
The MIT License (MIT). Please see LICENSE for more information., (*48)
Wallogit.com
