Download the PHP package dcardenasl/ci4-api-core without Composer

ci4-api-core

DTO-first API runtime foundation for CodeIgniter 4: base classes, HTTP layer, services, repositories, filters, audit chain, and queue. Drop into any CodeIgniter 4 project. Pair with dcardenasl/ci4-api-scaffolding for CRUD generation.

Status: v0.4.x (pre-release) — published on Packagist. APIs may still change before 1.0.0. Pin to ~0.4.0 or an exact version in production until 1.0.

Contents

• Quick Start
• What it does
• Why a package
• Runtime foundation
• Requirements
• Installation
• Configure
• Usage
• Field syntax
• Scope and limitations
• Customization
• Scaffolding contract
• Wiring assumption
• Troubleshooting
• See also
• Toward 1.0
• Development
• License

Quick Start

What it does

Package boundary: ci4-api-core provides the runtime foundation — base classes, HTTP layer, services, repositories, models, filters, audit chain, queue, and security utilities. The scaffolding engine (generators, make-crud.sh, spark commands) lives in the companion package dcardenasl/ci4-api-scaffolding. The flowchart below shows the full system when both packages are installed.

Generates a complete, production-ready CRUD module from a single command:

Outputs:

• 4 DTOs (Index/Create/Update request + Response) with validation and OpenAPI annotations
• Service interface + implementation extending your base CRUD service
• Controller with explicit CRUD methods and OpenAPI doc class
• Timestamped database migration
• Model + Entity extending your auditable base
• Route file under app/Config/Routes/v1/{domain-kebab}.php
• Language files (en + es)
• Unit / Integration / Feature test skeletons
• Service registrations injected into Config/Services.php (or printed for manual paste with --no-wire)

Why a package

The engine was being copied between projects manually, leading to drift. Extracting it gives:

• Single source of truth — bug fixes apply to all consumers via composer update.
• Versioned upgrades — projects pin to a constraint and adopt new versions when ready.
• Configurable conventions — base class FQCNs, paths, and route filters are declared per project in Config\Scaffolding.

Runtime foundation

ci4-api-core ships the classes that generated (and hand-written) modules extend and depend on at runtime:

Requirements

• PHP ^8.2
• CodeIgniter 4 ^4.6

Installation

Configure

Runtime — Config\Api (optional)

ci4-api-core reads an optional Config\Api class for search and pagination knobs. Defaults are safe when absent:

Scaffolding — Config\Scaffolding (ci4-api-scaffolding)

Create app/Config/Scaffolding.php in your project. If your project follows the default conventions exactly, a one-liner is sufficient:

If omitted, the spark commands fall back to ScaffoldingConfig::defaults() with a warning.

Wiring — php spark core:install

After adding the package, run the wiring wizard to inject the required service factories into app/Config/Services.php:

The command detects which of the 4 required factories are already present and generates only the missing stubs. Re-running against an already-wired project is a no-op.

Usage

Scaffold a new CRUD module

Always wrap <Fields> in single quotes — the | modifier separator is shell-special.

Options

Validate and apply

After scaffolding, run in order:

Remove a module

Deletes all generated artifacts and un-wires the service registration.

Field syntax

Format: name:type:modifier1|modifier2

Supported types:

Supported modifiers:

Invalid or reserved field names are rejected upfront (PHP keywords, MySQL reserved words, id, created_at, updated_at, deleted_at).

Scope and limitations (v0.x)

The generator is designed for flat resources: one resource = one table = one set of CRUD endpoints. This is intentional — most domain entities are flat, and "smart" relation handling tends to over-engineer the simple case.

What fk:<table> does today:

• Adds an INT UNSIGNED column with the right name ({name}_id if you write category_id:fk:categories).
• Generates a FOREIGN KEY constraint in the migration.
• Adds is_not_unique[table.id] validation to the Create DTO so non-existent IDs are rejected at the API boundary.
• Optionally validates the target table exists at scaffold time (DB-reachability check; opt-out with --skip-fk-validation).

What it does NOT do — wire by hand if you need it:

• ❌ No hasMany / belongsTo accessor methods on the Entity.
• ❌ No automatic eager-loading of the related resource in the Response DTO (the parent is returned as category_id: int, not category: {...}).
• ❌ No nested route shapes (e.g. GET /categories/{id}/products).
• ❌ No reverse-side scaffolding (creating a Product does not regenerate the Category Service to expose getProducts()).
• ❌ No transactional cross-resource creation (e.g. POSTing a Category with embedded Product[] payloads).

If your domain needs any of the above, scaffold both resources flat first, then hand-edit the Service / Response DTO of the parent to load and expose the child collection. This is rarely more than ~30 lines of code per relation, and keeps the generator's surface small enough to remain stable across versions.

Roadmap: relation-aware generators are tracked in ci4-api-scaffolding's backlog (CRUD-003). The pre-1.0 API may still change.

Customization

Override any convention by passing a customized ScaffoldingConfig from your build() method:

ScaffoldingPaths defaults (relative to APPPATH, except tests which are relative to ROOTPATH):

Scaffolding contract

The engine generates code that extends specific base classes. Your project must provide these (or override them in Config\Scaffolding):

These are the defaults in ScaffoldingConfig::defaults().

Wiring assumption

ConfigWireman (the auto-wiring component) uses regex injection against app/Config/Services.php. It looks for a trait import line matching use {Domain}DomainServices; and injects the new service factory method there. If your Services.php has a non-standard layout, pass --no-wire and paste the printed snippet manually.

Troubleshooting

php spark make:crud prompted me for fields even though I passed --fields='…' You're in a non-TTY environment and the shell consumed the pipe characters. Use vendor/bin/make-crud.sh — it handles quoting correctly and is safe in CI and automation scripts.

Routes return 404 after scaffolding CI4 loads route files at boot only. Restart the server:

ScaffoldConflictException: files already exist Artifacts from a previous scaffold are still on disk. Either migrate + commit the previous module, or remove the stale files and try again. The orchestrator rolls back partial writes on failure, so the conflict is always pre-existing state, not a failed run.

Pre-commit hook rejects generated files vendor/bin/make-crud.sh runs composer cs-fix automatically post-generation. If you used php spark make:crud directly:

Never skip with --no-verify.

Auto-wiring silently skipped The commands fall back to --no-wire behaviour if they cannot locate the trait import line. Check the output — it will print the snippet for manual paste. Use --no-wire explicitly if your Services.php layout differs from the default.

See also

• docs/ARCHITECTURE_CONTRACT.md — non-negotiable layer rules for modules built on this package.
• docs/CRUD_FROM_ZERO.md — step-by-step playbook for scaffolding a module from a blank field spec.
• docs/SUPPORT_UTILITIES.md — RelationLabelLoader, CacheHelper, DateHelper: benefits, usage guide, and API reference.
• docs/EXTENDING_IAM.md — plug in any identity provider (Shield, OAuth, Keycloak, …).
• docs/EXTENDING_THROTTLE.md — custom rate-limit strategies.
• docs/EXTENDING_QUEUE.md — alternative queue backends.
• docs/EXTENDING_AUDIT.md — replace or extend the audit pipeline.

Toward 1.0

What is stable today

The following surfaces have integration tests and are considered stable. Changes here will carry a BREAKING tag in the changelog.

What may still change before 1.0

Criteria for 1.0.0

1. All stable-surface classes have integration tests with verified behavior.
2. HealthChecker accepts an injected BaseConnection — testable without a live database.
3. At least one documented real-world consumer running in production.
4. Infection PHP Mutation Score Indicator (MSI) ≥ 80% across the Unit + Integration suite.
5. No open BREAKING items in CHANGELOG.md [Unreleased].

Development

Tests run without bootstrapping a CI4 app — tests/bootstrap.php defines the minimum APPPATH/ROOTPATH shims.

License

MIT — see LICENSE.