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.

👉 View Full Roadmap on Wiki

🧠 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:

🔒 4. Security Attributes

Protect sensitive data with declarative security:

🛡️ 5. Built-in Security

Enterprise-grade security out of the box:

✅ 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:

🔎 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

🛠️ 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