BlackPearl is a simple and lightweight PHP MVC (Model-View-Controller) framework used for building full-stack web applications in PHP. It utilizes well-known PHP packages and libraries that you may already be familiar with, such as the Blade Templating Engine for the user interface and the Eloquent ORM (Object-Relational Mapping) system for database interaction. BlackPearl also implements a classic routing system and database migration system to enhance the developer experience.
composer create-project blackpearl/blackpearl Project_Name
You can configure your environment variables in the .env file.
Commands
You can see available commands by typing php smark on your terminal.
php -S localhost:1000.
Routing functionality is centralized within the 'routes/router.php' file. This file serves as the hub where all routes for the application are registered and managed. Here, developers can define the endpoints and corresponding actions that dictate how incoming requests are handled and processed within the application. By consolidating routing configuration in a dedicated file, BlackPearl promotes clarity and ease of maintenance, ensuring that developers can efficiently manage the application's navigation and functionality. This centralized approach to routing not only enhances organization but also facilitates rapid development and scalability, allowing for seamless expansion and modification of application routes as project requirements evolve.
$route->add('home', '/home', [HomeController::class, 'index']);Controllers play a pivotal role and are centrally located within the 'controllers' folder. These controllers serve as repositories for the application's logic, encapsulating the essential business rules and operational workflows that define its functionality. By organizing logic into controllers, BlackPearl promotes a structured approach to development, enhancing clarity and maintainability across projects. Each controller within BlackPearl is responsible for specific actions and processes, facilitating a modular and scalable architecture. This design not only improves code organization and readability but also supports efficient management and extension of application features. Overall, BlackPearl's emphasis on controller-based architecture underscores its commitment to empowering developers to build robust and maintainable PHP applications effectively.
Make a controller:
php smark make:controller ControllerName Example Controller:
namespace App\Controller;
use Framework\BlackPearl\View;
class HomeController
{
public function index()
{
return View::render('home', []);
}
}Middleware is an essential component in the BlackPearl framework, strategically positioned to enhance the request-response lifecycle. Located within the 'middleware' folder, these middleware components act as intermediaries, processing HTTP requests before they reach the controllers and handling responses before they are sent to the client. Middleware functions encapsulate various cross-cutting concerns such as authentication, logging, and input validation, ensuring these tasks are performed consistently and efficiently across the application.
Make a middleware:
php smark make:middleware MiddlewareName Example Middleware (Auth middleware):
namespace App\Controller;
use Framework\BlackPearl\View;
use Framework\BlackPearl\Auth;
class HomeController
{
public function index()
{
Auth::check() // this middleware will check if the user is authenticated before proceeding.
return View::render('home', []);
}
}If middleware detects an unauthenticated user, it will redirect to the login page.
Policy in the BlackPearl framework is a crucial component designed to manage access control within the application. Located within the 'policies' folder, these policy classes define the authorization logic that determines what actions a user can perform on a given resource. Policies provide a centralized and organized approach to implementing permissions, ensuring that access rules are clear, consistent, and easily maintainable.
Make a policy:
php smark make:policy PolicyName Example Policy (UserAccessPolicy policy):
namespace App\Policy;
use Exception;
use Framework\BlackPearl\Auth;
class UserAccessPolicy
{
// Determine whether the user can create a resource.
public static function create($user) {
return ($user === Auth::user()->id) ? true : throw new Exception('This action is unauthorize');
}
// Determine whether the user can update a resource.
public static function update($user, $model) {
return ($user === $model) ? true : throw new Exception('This action is unauthorize');
}
// Determine whether the user can delete a resource.
public static function delete($user, $model) {
return ($user === $model) ? true : throw new Exception('This action is unauthorize');
}
}Usage on controller:
namespace App\Controller;
use App\Policy\UserAccessPolicy;
use Framework\BlackPearl\Auth;
use Framework\BlackPearl\View;
class HomeController
{
public function index()
{
UserAccessPolicy::create(Auth::user()->id); // determine whether a user (logged in user) has permission to create a specific resource.
return View::render('home', []);
}
}The model layer of the MVC (Model-View-Controller) architecture is stored within the designated 'models' folder. Models in BlackPearl represent the essential data structures and business logic of the application, encapsulating interactions with the database and defining how data is manipulated and accessed. By segregating models into a dedicated folder, BlackPearl promotes a clear separation of concerns, enhancing code organization and maintainability. Each model within the 'models' folder corresponds to a specific entity or resource within the application, defining its properties, relationships with other models, and methods for data retrieval and manipulation. This structured approach to modeling not only facilitates efficient data management but also supports the scalability and extensibility of the application, empowering developers to build robust and scalable PHP applications with ease.
Make a model:
php smark make:model ModelName
This command will automatically add a database migration as well. See on database/migrations/tables.php.
Example Model:
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
protected $table = 'users'; // define table
protected $fillable = [
'name',
'email',
'password'
];
}Example Migration Table: (todo table from a Todo model)
/* todos table */
Capsule::schema()->create('todo', function (Blueprint $table) {
$table->increments('id');
$table->string('todo');
$table->timestamps();
});The view layer of the MVC (Model-View-Controller) architecture resides within the designated 'views' folder. Views in BlackPearl encompass the presentation layer of the application, responsible for rendering user interfaces and displaying data to the end user. By organizing views into a centralized folder, BlackPearl promotes a structured approach to managing frontend components, enhancing code organization and facilitating efficient maintenance. Each view within the 'views' folder corresponds to a specific page or component within the application, incorporating HTML markup along with embedded PHP or template engine syntax for dynamic content generation. This separation of concerns allows developers to focus on designing responsive and visually appealing interfaces while leveraging the underlying logic encapsulated in controllers and models. By adhering to best practices in view management, BlackPearl empowers developers to create intuitive and scalable PHP applications that deliver seamless user experiences.
Make a view:
php smark make:view view-name Example View:
@extends('layouts.app')
@section('content')
{{-- Silence is golden --}}
@endsectionuse Framework\BlackPearl\BarCode;
BarCode::generate('I love BlackPearl!');
use Framework\BlackPearl\API;
API::json([
"name" => "Mark Jason Espelita",
"age" => 24
]); // this will return a ContentType/json document.
API::response([
"name" => "Mark Jason Espelita",
"age" => 24
]); // this will return a simple json.
Using Eloquent ORM.
use Framework\BlackPearl\Excel;
use Framework\Models\User;
Excel::downloadExcel(array(
array(
'name' => 'Name',
'email' => 'Email'
)
), User::select('name', 'email')->get());
Using Eloquent ORM and provide Excel file name.
use Framework\BlackPearl\Excel;
use Framework\Models\User;
Excel::downloadExcelAs('myExcelReport', array(
array(
'name' => 'Name',
'email' => 'Email'
)
), User::select('name', 'email')->get());
use Framework\BlackPearl\File;
File::upload($_FILES['fileInput'], '../storage/', ['jpg', 'jpeg', 'png']);
use Framework\BlackPearl\JSON;
// Read JSON file data.
JSON::read('../path/to/data.json');
// Push data (to the last item).
JSON::push('../path/to/data.json', array(
array(
'id' => uniqid('', true),
'name' => 'Mark Jason',
'age' => 24
)
));
// Unshift data (to the first item).
JSON::unshift('../path/to/data.json', array(
array(
'id' => uniqid('', true),
'name' => 'Mark Jason',
'age' => 24
)
));
// Delete data.
JSON::delete('../path/to/data.json', 'id', 1); // where id = 1
// Update data.
JSON::update('../path/to/data.json', 'id', 1, 'name', 'Mark Jason Updated Name'); // update name = Mark Jason Updated Name where id = 1
use Framework\BlackPearl\Mail;
Mail::sendMail(
'markjasonespelita@gmail.com', // sender email
'-- app password secret --', // sender email app password
'markjasonespelita@gmail.com', // send from email (sender)
'Mark Jason Espelita', // send from name (sender)
'mark.medivadigital@gmail.com', // reciever email
'markjasonespelita@gmail.com', // reply to email
'Mark Jason Espelita', // reply to name
'Hello World', // subject
'Hi Mark, This is a sample message from BlackPearl!' // body (in HTML format)
);
use Framework\BlackPearl\Math;
// Addition
Math::compute('add', [2, 3]);
// Subtraction
Math::compute('minus', [2, 3]);
// Multiplication
Math::compute('multiply', [2, 3]);
// Division
Math::compute('divide', [2, 3]);