README

🪄 BOUNDLY

The Metadata-Driven PHP Framework

Build enterprise-grade APIs by defining only your Domain. Everything else is automatic.

Metadata-driven. Convention-over-Configuration. Zero Boilerplate.

🗺️ Roadmap & Strategy

Stay updated on our progress toward v1.0.0. We are currently in active alpha development.

🧠 What is BOUNDLY?

BOUNDLY is a high-performance PHP framework that uses Metadata-Driven Architecture and Convention-over-Configuration. It eliminates boilerplate code by using PHP 8+ Attributes as the single source of truth for your infrastructure.

You define your Domain (entities, actions, business logic). BOUNDLY handles the Infrastructure (routes, controllers, validation, persistence).

✅ Zero manual migrations — Your DB schema evolves with your code.
✅ Zero route files — Your endpoints are declared on your Actions.
✅ Zero boilerplate repositories — Generic CRUD is handled automatically.
✅ Zero validation rules — Payloads are validated against your entity attributes.
✅ Enterprise features in one line — Auditing, Soft Delete, Multi-Tenancy, Authorization, Rate Limiting.
✅ Real-Time Agnostic — Propagate Domain Events to WebSockets without coupling your logic to a visual driver.
✅ Production-ready — Static metadata cache, migration history, OpenAPI docs, and full CI/CD included.

🏛️ Architecture: Pure DDD

BOUNDLY enforces a clean, screaming architecture where the folder structure tells you what the system does, not what framework it uses.

/
├── Application/          # Use Cases (Actions, DTOs)
│   └── Users/
│       ├── Actions/      # #[Action] defines the API endpoint
│       └── DTOs/
├── Domain/               # Pure Business Logic
│   └── Users/
│       ├── Entities/     # #[Entity] defines the DB table
│       ├── Events/
│       └── ValueObjects/
├── Infrastructure/       # Technical Adapters
│   ├── FrameworkCore/    # The BOUNDLY Engine (CLI, Repos, Attributes)
│   └── LaravelEngine/   # Laravel internals (config, storage, routes...)
├── bootstrap/            # Framework ignition point
├── config/               # Your project config (boundly.php)
├── public/               # Web entry point
└── artisan               # CLI entry point

🔥 Key Features

🧬 1. Magic Evolution (Auto DB Sync)

Forget php artisan migrate. Define your entity, run the daemon, and your database evolves automatically.

#[Entity(table: 'users', resource: 'users')]
#[Auditable]
#[SoftDelete]
class User extends AggregateRoot
{
    #[Id]
    private int $id;

    #[Column(type: 'string', length: 150)]
    private string $name;

    #[Column(type: 'string', nullable: true, default: '555-0000')]
    private string $phone;
}

Run php artisan core:watch and your /api/users endpoint is live. ✨

🔐 2. Declarative Authorization

Protect any resource with a single attribute — no route middleware, no guards to register manually:

// Only admins and managers can access this resource
#[Entity(table: 'salaries', resource: 'salaries')]
#[Authorize(roles: ['admin', 'manager'])]
class Salary extends AggregateRoot { ... }

// Public reads, auth required for writes
#[Entity(table: 'articles', resource: 'articles')]
#[Authorize(roles: [], methods: ['POST', 'PUT', 'PATCH', 'DELETE'])]
class Article extends AggregateRoot { ... }

🛡️ 3. Declarative Behavioral Traits

Add enterprise features with a single attribute:

Attribute	What it does
`#[Auditable]`	Injects `created_by` / `updated_by` — auto-populated from the request
`#[SoftDelete]`	Handles `deleted_at` and filters queries silently
`#[TenantAware]`	Multi-tenant data isolation at the repository level
`#[Authorize]`	Role-based access control — reads PHP Attributes, not config files
`#[Blameable]`	Extended audit trail tracking created_by/updated_by/deleted_by
`#[Timestampable]`	Auto-manage created_at/updated_at timestamps
`#[Sluggable]`	Auto-generate URL-friendly slugs from another field
`#[Policy]`	Map Laravel Policies for fine-grained authorization

🔒 4. Security Attributes

Protect sensitive data with declarative security:

Attribute	What it does
`#[Hidden]`	Exclude properties from API responses
`#[Encrypted]`	Encrypt at rest with AES-256-CBC
`#[Hashed]`	One-way hashing (bcrypt/Argon2)
`#[RateLimit]`	API rate limiting with per-IP/user tracking

🛡️ 5. Built-in Security

Enterprise-grade security out of the box:

Feature	Description
Input Sanitization	Whitelist approach - only declared columns are accepted
SQL Injection Prevention	Column whitelist validation in DynamicRepository
Rate Limiting	Built-in `#[RateLimit]` attribute
Authorization	`#[Authorize]` attribute with role-based access control

✅ 6. 40+ Validation Attributes

Comprehensive data validation out of the box:

Type: Email, Url, IpAddress, Uuid, Json, IsoDate, Timezone, ColorHex, Slug, MacAddress
Numeric: Min, Max, Between, Positive, Negative, Integer, Decimal
String: MinLength, MaxLength, LengthBetween, Alpha, Alphanumeric, Numeric, Pattern, StartsWith, EndsWith, Contains
Format: Phone, CreditCard, PostalCode, Coordinates
Database: Unique, Exists, Enum
File: Image, Mimes, FileSize
Compound: Required, Confirmed, Password, StrongPassword, SameAs, DifferentFrom

🔗 7. Complete Relations Suite

All relationship types supported:

Relation	Attribute
One-to-Many	`#[BelongsTo]` / `#[HasMany]`
One-to-One	`#[HasOne]`
Many-to-Many	`#[ManyToMany]` (with pivot sync)
Polymorphic	`#[MorphTo]` / `#[MorphMany]` / `#[MorphOne]`

🔎 8. Pro Query Engine

Complex filtering, nested eager loading, and dual pagination out-of-the-box:

# Partial search
GET /api/users?name_like=boundly

# Range filtering with new operators
GET /api/users?age_gte=18&score_lte=100

# NOT and IN operators
GET /api/products?category_not=5&id_in=1,2,3

# OR filter groups
GET /api/users?or[name_like]=john&or[email_like]=john

# Nested eager loading (dot-notation)
GET /api/users?include=posts.comments.author

# Cursor pagination (efficient for large datasets)
GET /api/events?cursor=250&per_page=20

# Sorting & standard pagination
GET /api/users?sort=name&direction=asc&per_page=20

🌍 9. Full Internationalization (i18n)

Console output speaks your language:

php artisan core:watch --lang=es

📡 10. Agnostic WebSockets Bridge

Broadcast your domain events to the frontend in real-time, completely decoupled from infrastructure (Reverb, Pusher, Soketi) using the purely semantic ShouldBroadcastToExterior contract. Read the Integration Guide

🚀 Quick Start

1. Create a new project

composer create-project epolabs/boundly boundly --stability=alpha
cd my-project

Or clone the repository:

git clone https://github.com/EpOpenLabs/BOUNDLY.git my-project
cd my-project
composer install

2. Configure environment

cp .env.example .env
php artisan key:generate

Configure your database in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=my_project
DB_USERNAME=root
DB_PASSWORD=secret

2. Configure your database

# .env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=my_project
DB_USERNAME=root
DB_PASSWORD=secret

3. Define your Entity

// Domain/Users/Entities/User.php
#[Entity(table: 'users', resource: 'users')]
#[Auditable]
class User extends AggregateRoot
{
    #[Id]
    private int $id;

    #[Column(type: 'string', length: 150)]
    private string $name;

    #[Column(type: 'string', unique: true)]
    private string $email;
}

4. Start the daemon

php artisan core:watch

🎉 Your API is live at http://localhost:8000/api/users.

5. Before deploying to production

# Preview schema changes
php artisan core:migrate --dry-run

# Apply schema
php artisan core:migrate

# Cache metadata for zero-overhead boot
php artisan core:cache

# Generate OpenAPI documentation
php artisan core:docs

⚙️ Configuration Reference

Key	Default	Env Variable	Description
`locale`	`en`	`BOUNDLY_LOCALE`	Default language for CLI output
`api_prefix`	`api`	`BOUNDLY_API_PREFIX`	URL prefix for all auto-generated routes
`disable_cache`	`true` in local	`BOUNDLY_DISABLE_CACHE`	Forces scan mode; set `false` in production
`auth.default_guard`	`sanctum`	`BOUNDLY_AUTH_GUARD`	Guard used by `#[Authorize]` middleware
`pagination.default_per_page`	`15`	`BOUNDLY_PER_PAGE`	Default page size
`pagination.max_per_page`	`100`	`BOUNDLY_MAX_PER_PAGE`	Hard cap on page size
`rate_limit.enabled`	`true`	`BOUNDLY_RATE_LIMIT_ENABLED`	Enable/disable rate limiting
`rate_limit.max_attempts`	`60`	`BOUNDLY_RATE_LIMIT_MAX_ATTEMPTS`	Max requests per window
`rate_limit.decay_minutes`	`1`	`BOUNDLY_RATE_LIMIT_DECAY_MINUTES`	Time window in minutes
`paths.domain`	`Domain/`	—	Where BOUNDLY scans for `#[Entity]`
`paths.application`	`Application/`	—	Where BOUNDLY scans for `#[Action]`

🛠️ Requirements

PHP 8.2+
Laravel 13+ (core dependency, hidden in Infrastructure/LaravelEngine)
MySQL / PostgreSQL / SQLite

🤝 Contributing

BOUNDLY is an open source project and contributions are welcome!

Please read CONTRIBUTING.md for details on:

How to report bugs
How to propose new features
The Pull Request process
Code style guidelines

📋 Versioning

BOUNDLY follows Semantic Versioning (SemVer):

MAJOR → Breaking changes in the API or architecture
MINOR → New backward-compatible features
PATCH → Bug fixes

See the full history in CHANGELOG.md.

📜 License

BOUNDLY is open-sourced software licensed under the MIT License.

☕ Support the Project

If BOUNDLY has been useful to you or you like what we're building, you can support us to keep creating and maintaining open source software:

A coffee = more time for open source code ❤️

⭐ If you like BOUNDLY, give it a star on GitHub! ⭐

GitHub · Issues · Discussions

Made with ❤️ by EpOpenLabs

epolabs / boundly

Maintainers

Package info

Statistics

Security