core/php-framework
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
php-framework/CREATING-TEMPLATE-REPO.md

13 KiB
Raw Blame History

Creating the Core PHP Framework Template Repository

This guide explains how to create the host-uk/core-template GitHub template repository that php artisan core:new will use to scaffold new projects.

Overview

The template repository is a minimal Laravel application pre-configured with Core PHP Framework packages. Users run:

php artisan core:new my-project

This clones the template, configures it, and installs dependencies automatically.

Repository Structure

host-uk/core-template/
├── app/
│   ├── Console/
│   ├── Http/
│   ├── Models/
│   └── Providers/
├── bootstrap/
│   └── app.php              # Core packages registered here
├── config/
│   ├── app.php
│   ├── database.php
│   └── core.php             # Core framework config
├── database/
│   ├── migrations/
│   └── seeders/
├── public/
├── resources/
│   ├── views/
│   └── css/
├── routes/
│   ├── api.php
│   ├── console.php
│   └── web.php
├── storage/
├── tests/
├── .env.example
├── .gitignore
├── composer.json            # Pre-configured with Core packages
├── package.json
├── phpunit.xml
├── README.md
└── vite.config.js

Step 1: Create Base Laravel App

# Create fresh Laravel 12 app
composer create-project laravel/laravel core-template
cd core-template

Step 2: Configure composer.json

Update composer.json to require Core PHP packages:

{
    "name": "host-uk/core-template",
    "type": "project",
    "description": "Core PHP Framework - Project Template",
    "keywords": ["laravel", "core-php", "modular", "framework", "template"],
    "license": "EUPL-1.2",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^12.0",
        "laravel/tinker": "^2.10",
        "livewire/flux": "^2.0",
        "livewire/flux-pro": "^2.10",
        "livewire/livewire": "^3.0",
        "host-uk/core": "^1.0",
        "host-uk/core-admin": "^1.0",
        "host-uk/core-api": "^1.0",
        "host-uk/core-mcp": "^1.0"
    },
    "require-dev": {
        "fakerphp/faker": "^1.23",
        "laravel/pail": "^1.2",
        "laravel/pint": "^1.18",
        "laravel/sail": "^1.41",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.6",
        "phpunit/phpunit": "^11.5"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Website\\": "app/Website/",
            "Database\\Factories\\": "database/factories/",
            "Database\\Seeders\\": "database/seeders/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "repositories": [
        {
            "name": "flux-pro",
            "type": "composer",
            "url": "https://composer.fluxui.dev"
        }
    ],
    "scripts": {
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ],
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ],
        "post-root-package-install": [
            "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
        ],
        "post-create-project-cmd": [
            "@php artisan key:generate --ansi",
            "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
            "@php artisan migrate --graceful --ansi"
        ]
    },
    "extra": {
        "laravel": {
            "dont-discover": []
        }
    },
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist",
        "sort-packages": true,
        "allow-plugins": {
            "php-http/discovery": true
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Step 3: Update bootstrap/app.php

Register Core PHP packages:

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withProviders([
        // Core PHP Framework Packages
        Core\CoreServiceProvider::class,
        Core\Mod\Admin\Boot::class,
        Core\Mod\Api\Boot::class,
        Core\Mod\Mcp\Boot::class,
    ])
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

Step 4: Create config/core.php

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Core PHP Framework Configuration
    |--------------------------------------------------------------------------
    */

    'module_paths' => [
        base_path('packages/core-php/src/Mod'),
        base_path('packages/core-php/src/Core'),
        base_path('app/Mod'),
    ],

    'services' => [
        'cache_discovery' => env('CORE_CACHE_DISCOVERY', true),
    ],

    'cdn' => [
        'enabled' => env('CDN_ENABLED', false),
        'driver' => env('CDN_DRIVER', 'bunny'),
    ],
];

Step 5: Update .env.example

Add Core PHP specific variables:

APP_NAME="Core PHP App"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_TIMEZONE=UTC
APP_URL=http://localhost

APP_LOCALE=en_GB
APP_FALLBACK_LOCALE=en_GB
APP_FAKER_LOCALE=en_GB

DB_CONNECTION=sqlite
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=core
# DB_USERNAME=root
# DB_PASSWORD=

# Core PHP Framework
CORE_CACHE_DISCOVERY=true

# CDN Configuration
CDN_ENABLED=false
CDN_DRIVER=bunny
BUNNYCDN_API_KEY=
BUNNYCDN_STORAGE_ZONE=
BUNNYCDN_PULL_ZONE=

# Flux Pro (optional)
FLUX_LICENSE_KEY=

Step 6: Create README.md

# Core PHP Framework Project

A modular monolith Laravel application built with Core PHP Framework.

## Features

✅ **Core Framework** - Event-driven module system with lazy loading
✅ **Admin Panel** - Livewire-powered admin interface with Flux UI
✅ **REST API** - Scoped API keys, rate limiting, webhooks, OpenAPI docs
✅ **MCP Tools** - Model Context Protocol for AI agent integration

## Installation

### From Template (Recommended)

```bash
# Using the core:new command
php artisan core:new my-project

# Or manually clone
git clone https://github.com/host-uk/core-template.git my-project
cd my-project
composer install
php artisan core:install

Requirements

  • PHP 8.2+
  • Composer 2.x
  • SQLite (default) or MySQL/PostgreSQL
  • Node.js 18+ (for frontend assets)

Quick Start

# 1. Install dependencies
composer install
npm install

# 2. Configure environment
cp .env.example .env
php artisan key:generate

# 3. Set up database
touch database/database.sqlite
php artisan migrate

# 4. Start development server
php artisan serve

Visit: http://localhost:8000

Project Structure

app/
├── Mod/          # Your custom modules
├── Website/      # Multi-site website modules
└── Providers/    # Laravel service providers

config/
└── core.php      # Core framework configuration

routes/
├── web.php       # Public web routes
├── api.php       # REST API routes (via core-api)
└── console.php   # Artisan commands

Creating Modules

# Create a new module with all features
php artisan make:mod Blog --all

# Create module with specific features
php artisan make:mod Shop --web --api --admin

Modules follow the event-driven pattern:

<?php
namespace Mod\Blog;

class Boot
{
    public static array $listens = [
        WebRoutesRegistering::class => 'onWebRoutes',
        ApiRoutesRegistering::class => 'onApiRoutes',
        AdminPanelBooting::class => 'onAdminPanel',
    ];

    public function onWebRoutes(WebRoutesRegistering $event): void
    {
        $event->routes(fn() => require __DIR__.'/Routes/web.php');
    }
}

Core Packages

  • host-uk/core - Core framework components
  • host-uk/core-admin - Admin panel with Livewire modals
  • host-uk/core-api - REST API with scopes & webhooks
  • host-uk/core-mcp - Model Context Protocol tools for AI

Documentation

License

EUPL-1.2 (European Union Public Licence)


---

## Step 7: Add .gitattributes

```gitattributes
* text=auto

*.blade.php diff=html
*.css diff=css
*.html diff=html
*.md diff=markdown
*.php diff=php

/.github export-ignore
CHANGELOG.md export-ignore

Step 8: Create GitHub Repository

On GitHub:

  1. Create new repository

    • Name: core-template
    • Description: "Core PHP Framework - Project Template"
    • Public repository
    • ✅ Check "Template repository"

  2. Push your code

git init
git add .
git commit -m "Initial Core PHP Framework template"
git branch -M main
git remote add origin https://github.com/host-uk/core-template.git
git push -u origin main

  1. Configure template settings

    • Go to Settings → General
    • Under "Template repository", enable checkbox
    • Add topics: laravel, core-php, modular-monolith, template

  2. Create releases

    • Tag: v1.0.0
    • Title: "Core PHP Framework Template v1.0.0"
    • Include changelog

Step 9: Test Template Creation

# Test the template works
php artisan core:new test-project

# Should create:
# - test-project/ directory
# - Run composer install
# - Run core:install
# - Initialize git repo

cd test-project
php artisan serve

Additional Template Variants

You can create specialized templates:

API-Only Template

Repository: host-uk/core-api-template Usage: php artisan core:new my-api --template=host-uk/core-api-template

Includes only:

  • core
  • core-api
  • Minimal routes (API only)

Admin-Only Template

Repository: host-uk/core-admin-template Usage: php artisan core:new my-admin --template=host-uk/core-admin-template

Includes only:

  • core
  • core-admin
  • Auth scaffolding

SaaS Template

Repository: host-uk/core-saas-template Usage: php artisan core:new my-saas --template=host-uk/core-saas-template

Includes:

  • All core packages
  • Multi-tenancy pre-configured
  • Billing integration stubs
  • Feature flags

Updating the Template

When you release new core package versions:

  1. Update composer.json with new version constraints
  2. Update .env.example with new config options
  3. Update README.md with new features
  4. Tag a new release: v1.1.0, v1.2.0, etc.

Users can specify template versions:

php artisan core:new my-project --template=host-uk/core-template --branch=v1.0.0

GitHub Actions (Optional)

Add .github/workflows/test-template.yml to test template on every commit:

name: Test Template

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2
          extensions: sqlite3

      - name: Install Dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Copy .env
        run: cp .env.example .env

      - name: Generate Key
        run: php artisan key:generate

      - name: Create Database
        run: touch database/database.sqlite

      - name: Run Migrations
        run: php artisan migrate --force

      - name: Run Tests
        run: php artisan test

Maintenance

Regular Updates

  • Monthly: Update Laravel & core package versions
  • Security: Apply security patches immediately
  • Testing: Test template creation works after updates

Community Templates

Encourage community to create their own templates:

# Community members can create templates like:
php artisan core:new my-blog --template=johndoe/core-blog-template
php artisan core:new my-shop --template=acme/core-ecommerce

Support

For issues with the template:

Checklist

Before publishing the template:

  • All core packages install without errors
  • php artisan core:install runs successfully
  • Database migrations work
  • php artisan serve starts server
  • Admin panel accessible at /admin
  • API routes respond correctly
  • MCP tools registered
  • README.md is clear and helpful
  • .env.example has all required variables
  • Repository is marked as "Template repository"
  • v1.0.0 release is tagged
  • License file is included (EUPL-1.2)

Template Ready! 🚀

Users can now run:

php artisan core:new my-awesome-project

And get a fully configured Core PHP Framework application in seconds.