simp/modal

This is package that will be standalone modal creations

v1.0.1 2025-09-12 18:37 UTC

Requires

• ext-pdo: *
• symfony/var-dumper: ^7.3

Requires (Dev)

• phpunit/phpunit: ^12

MIT

• CHANCENY

README

This project demonstrates a lightweight PHP Modal system with CRUD operations, relations, and query building.

Table of Contents

• Installation
• Initializing Modals
• Inserting Records
• Selecting Specific Columns
• Relations
  • User ↔ Role Relations
• Usage Examples
  • Has One Relation (User -> Role)
  • Has Many Relation (User -> Roles)
  • Belongs To Relation (Role -> User)
• Complex Query Example
• Update Example
• Delete Example
• Migrations
  • Create Migration
  • Run Migrate
  • Modify Migration
  • Drop Tables
• Notes

Installation

composer require simp/modal

Make sure your database is running and accessible. Update the database connection settings in example.php:

$db = new PDO('mysql:host=database;dbname=lamp', 'lamp', 'lamp');
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$db->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
$db->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);

Initializing Modals

$userModal = UserTestModal::getModal($db);
$roleModal = RoleTestModal::getModal($db);

Clear tables before seeding:

$db->exec("DELETE FROM {$roleModal->getTable()}");
$db->exec("ALTER TABLE {$roleModal->getTable()} AUTO_INCREMENT = 1");
$db->exec("DELETE FROM {$userModal->getTable()}");
$db->exec("ALTER TABLE {$userModal->getTable()} AUTO_INCREMENT = 1");

Inserting Records

$aliceId   = $userModal->fill(['name' => 'Alice', 'email' => '[e-mail]', 'password' => 'secret'])->insert();
$bobId     = $userModal->fill(['name' => 'Bob', 'email' => '[e-mail]', 'password' => 'pass'])->insert();
$charlieId = $userModal->fill(['name' => 'Charlie', 'email' => '[e-mail]', 'password' => '1234'])->insert();

$roleModal->fill(['role_name' => 'Admin', 'uid' => $aliceId])->insert();
$roleModal->fill(['role_name' => 'Editor', 'uid' => $bobId])->insert();
$roleModal->fill(['role_name' => 'Subscriber', 'uid' => $bobId])->insert();
$roleModal->fill(['role_name' => 'Viewer', 'uid' => $charlieId])->insert();

Selecting Specific Columns

$usersSelected = $userModal
    ->select(['id', 'name'])
    ->limit(3)
    ->orderBy('id', 'ASC')
    ->get();

Relations

User ↔ Role Relations

User -> hasOne Role
User -> hasMany Roles
Role -> belongsTo User

Diagram

+-----------------+        hasOne        +-----------------+
|      User       |--------------------->|       Role      |
|-----------------|                      |-----------------|
| id              |                      | id              |
| name            |                      | role_name       |
| email           |                      | uid (user_id)   |
| password        |                      | description     |
+-----------------+                      +-----------------+
       | 1
       | hasMany
       v
+-----------------+
|      Role       |
|-----------------|
| id              |
| role_name       |
| uid (user_id)   |
| description     |
+-----------------+

Usage Examples

Has One Relation (User -> Role)

$alice = $userModal->where('id', '=', $aliceId)->first();
$aliceRole = $roleModal->where('uid', '=', $alice['id'])
                       ->select(['role_name', 'uid'])
                       ->first();

Has Many Relation (User -> Roles)

$bob = $userModal->where('id', '=', $bobId)->first();
$bobRoles = $roleModal->where('uid', '=', $bob['id'])
                      ->select(['role_name','uid'])
                      ->get();

Belongs To Relation (Role -> User)

$editorRole = $roleModal->where('role_name', '=', 'Editor')->first();
$editorUser = $userModal->where('id', '=', $editorRole['uid'])
                        ->select(['name', 'email'])
                        ->first();

Complex Query Example

$complexUsers = $userModal
    ->whereIn('id', [$aliceId, $bobId])
    ->orWhere('name', '=', 'Charlie')
    ->select(['id', 'name', 'email'])
    ->orderBy('id', 'DESC')
    ->get();

// Attach hasMany roles for each user
foreach ($complexUsers as &$user) {
    $user['roles'] = $roleModal->where('uid', '=', $user['id'])
                               ->select(['role_name','uid'])
                               ->get();
}

Update Example

$updateCount = $userModal->where('id', '=', $aliceId)
                         ->fill(['name' => 'Alice Updated'])
                         ->update();

$updatedUser = $userModal->where('id', '=', $aliceId)->first();

Delete Example

$deleteCount = $roleModal->where('role_name', '=', 'Viewer')->delete();
$remainingRoles = $roleModal->get();

Notes

• Select: Choose specific columns with select().
• Where In / Or Where: Build complex queries with whereIn() and orWhere().
• Relations: Use hasOne, hasMany, and belongsTo to link modals.
• Query Reset: Each query resets automatically after execution.
• Mass Assignment: Use fill() for safe attribute assignment.