Environment Setting

First of all, you will need to look at the .env.example file located in the app root directory. Then, rename it to .env

By default, it has the following keys:

 # ---ENVIRONMENT--- #
 ## development or production
 ## DEV_SERVER=NATIVE or WAMP or XAMPP
 ## When using PHP NATIVE development server, BASE_URL=localhost:8000
 ## and run php -S localhost:8000 -t public server.php
 ## Otherwise, when using WAMP or XAMPP, BASE_URL=localhost/app_folder
 ## In production, BASE_URL=your-domain without protocol

 ENVIRONMENT=development
 DEV_SERVER=WAMP
 BASE_URL=localhost/zap

 # ---SESSION_NAME--- #
 SESSION_NAME=zapapp

 # ---DATABASE--- #
 ## DRIVER = mysql or sqlite
 DB_HOST=localhost
 DB_USER=root
 DB_PASS=
 DB_NAME=mydb
 DB_DRIVER=mysql
 DB_PORT=
 SQLITE_PATH=storage/database/${DB_NAME}.sqlite

 # ---EMAIL--- #
 EMAIL_HOST=
 EMAIL_USER=
 EMAIL_PASS=
 EMAIL_PORT=
 EMAIL_SECURE=

 # ---KEYS--- #
 ##Generate new key using php console generate --key
 ZAP_KEY=
 

The content is actually self-explained.

The most important thing is that initially .env does not exist and this will trigger an error. Thus, you will need to rename .env.example to .env as said before.

Set the ENVIRONMENT properly, whether development or production (production: when the development finished and the app is ready to deploy).

To get the key of the ENV key, you can use the read_env() helper:

read_env(string $key, mixed $default = null);
//example: $dbDriver = read_env('DB_DRIVER', 'mysql')

This will return mysql if the value of the key DB_DRIVER is empty or the key does not exist.

You can also use global variable like $_ENV['DB_DRIVER'] to get the same key. However, to prevent errors due to the key inexistence, please use the helper instead.

Development Server

Zap is developed using the WAMP Server app. However, it does not stop you from using other local PHP server app like XAMPP or the built-in PHP development server.

When using the PHP built-in development server, set the DEV_SERVER to NATIVE. Without this, the app cannot read the assets because the server app behaves differently. The BASE_URL is then need to be set to localhost:8000 or another open port in your machine.

To run the native development server, open terminal in the root folder and run the following command:

 php -S localhost:8000 -t public server.php
 

In our machine, using native or built-in PHP server is significantly slow. Thus, you are encouraged to use a third-party PHP development server app like WAMP or XAMPP.

In production, the BASE_URL needs to be adjusted. If the app is in the main domain, then put the domain name, e.g., yourdomain.com. Likewise, if the app is in a subdomain, use subdomain.domain.com. Once again, the BASE_URL is without the host protocol.

Session Name

Session name should be a space-free string, unique, and secret. This session name will be the default top-level key for $_SESSION['the_session_name'] of your app. Of course, new session names can be added when needed.

The session can be retrieved by using the following helper:

 config('app.session');
 

In fact, the config() helper function can be used for retrieving any configurations from the /config directory. In this case, app is the config file name, while session is the key. It is strongly recommended to change the key name, though the value remains (for security).

Database and Email

Database configuration consists of information, such as the host, username, password, port, and driver. When the driver is sqlite, the path to the sqlite file is required.

Currently, Zap database wrapper supports MySql and Sqlite. You can replace the database wrapper with those used in Laravel or Symfony. However, replacing the default database wrapper disables you from using Zap QueryBuilder and Schema (for migration).

By default, Zap initiates database connection in the BaseModel class. Singleton approach is used here to prevent multiple database initiation, which results in overheat. Moreover, although you extend the BaseModel in a model, database connection will be made when you use the built-in method db() or other CRUD methods in the BaseModel.

Email credential is optional, unless your app sends email, such as confirmation, password reset, campaign, etc.

By default, Zap uses PHPMailer as the email class. An utility class Email can also be used, which employs fluent. The basic use of this utility class is as follow:

use Zap\Core\Utils\Email;

$result = (new Email())
 ->sender_name('John Doe')
 ->addressee('jane@example.com', 'Jane Doe')
 ->subject('Welcome aboard!')
 ->body('<h1>Welcome!</h1><p>Thanks for joining us.</p>')
 ->execute();

if ($result['status'] === 'success') {
 echo "Email sent successfully!";
} else {
 echo "Failed to send: " . $result['message'];
}

You can also pass multiple BBCs by using:

->bbc([
 ['email'=>'manager@example.com', 'name'=>'Manager'],
 'archive@example.com'
])

And you can add attachments, whether from path or $_FILES['documents']

->attachment_from_path('path_to_attachment_1', 'path_to_attachment_2')
// or
->attachments($_FILES['documents'] ?? [])

Zap Key

Zap key is used to cipher and decipher sessions. Do not use the default key, if any, but generate one by using Zap CLI. Open the terminal in the root folder and use this command to generate a new key:

 php console generate --key
 

Then, copy the newly generated key and make it the value for ZAP_KEY in the .env file.