core/php-framework
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
php-framework/docs/guide/installation.md

4.8 KiB
Raw Blame History

Installation

This guide covers installing the Core PHP Framework in a new or existing Laravel application.

New Laravel Project

The quickest way to get started is with a fresh Laravel installation:

# Create new Laravel project
composer create-project laravel/laravel my-app
cd my-app

# Install Core PHP
composer require host-uk/core

# Install optional packages
composer require host-uk/core-admin  # Admin panel
composer require host-uk/core-api    # REST API
composer require host-uk/core-mcp    # MCP tools

Existing Laravel Project

Add to an existing Laravel 11+ or 12 application:

composer require host-uk/core

The service provider will be auto-discovered.

Package Installation

Install individual packages as needed:

Core Package (Required)

composer require host-uk/core

Provides:

  • Event-driven module system
  • Actions pattern
  • Multi-tenancy
  • Activity logging
  • Seeder auto-discovery

Admin Package (Optional)

composer require host-uk/core-admin

Provides:

  • Livewire admin panel
  • Global search
  • Service management UI
  • Form components

Additional requirements:

composer require livewire/livewire:"^3.0|^4.0"
composer require livewire/flux:"^2.0"

API Package (Optional)

composer require host-uk/core-api

Provides:

  • OpenAPI/Swagger documentation
  • Rate limiting
  • Webhook signing
  • Secure API keys

MCP Package (Optional)

composer require host-uk/core-mcp

Provides:

  • Model Context Protocol tools
  • Tool analytics
  • SQL query validation
  • MCP playground UI

Publishing Configuration

Publish configuration files:

# Publish core config
php artisan vendor:publish --tag=core-config

# Publish API config (if installed)
php artisan vendor:publish --tag=api-config

# Publish MCP config (if installed)
php artisan vendor:publish --tag=mcp-config

Database Setup

Run migrations:

php artisan migrate

This creates tables for:

  • Workspaces and users
  • API keys (if core-api installed)
  • MCP analytics (if core-mcp installed)
  • Activity logs (if spatie/laravel-activitylog installed)

Optional Dependencies

Activity Logging

For activity logging features:

composer require spatie/laravel-activitylog:"^4.8"
php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan migrate

Feature Flags

For feature flag support:

composer require laravel/pennant:"^1.0"
php artisan vendor:publish --provider="Laravel\Pennant\PennantServiceProvider"
php artisan migrate

Verify Installation

Check that everything is installed correctly:

# Check installed packages
composer show | grep host-uk

# List available artisan commands
php artisan list make

# Should see:
# make:mod       Create a new module
# make:website   Create a new website module
# make:plug      Create a new plugin

Environment Configuration

Add to your .env:

# Core Configuration
CORE_MODULE_DISCOVERY=true
CORE_STRICT_WORKSPACE_MODE=true

# API Configuration (if using core-api)
API_DOCS_ENABLED=true
API_DOCS_REQUIRE_AUTH=false
API_RATE_LIMIT_DEFAULT=60

# MCP Configuration (if using core-mcp)
MCP_ANALYTICS_ENABLED=true
MCP_QUOTA_ENABLED=true
MCP_DATABASE_CONNECTION=readonly

Directory Structure

After installation, your project structure will look like:

your-app/
├── app/
│   ├── Core/          # Core modules (framework-level)
│   ├── Mod/           # Feature modules (your code)
│   ├── Website/       # Website modules
│   └── Plug/          # Plugins
├── config/
│   ├── core.php       # Core configuration
│   ├── api.php        # API configuration (optional)
│   └── mcp.php        # MCP configuration (optional)
├── packages/          # Local package development (optional)
└── vendor/
    └── host-uk/       # Installed packages

Next Steps

Troubleshooting

Service Provider Not Discovered

If the service provider isn't auto-discovered:

composer dump-autoload
php artisan package:discover --ansi

Migration Errors

If migrations fail:

# Check database connection
php artisan db:show

# Run migrations with verbose output
php artisan migrate --verbose

Module Discovery Issues

If modules aren't being discovered:

# Clear application cache
php artisan optimize:clear

# Verify module paths in config/core.php
php artisan config:show core.module_paths

Minimum Requirements

  • PHP 8.2+
  • Laravel 11.0+ or 12.0+
  • MySQL 8.0+ / PostgreSQL 13+ / SQLite 3.35+
  • Composer 2.0+
  • 128MB PHP memory limit (256MB recommended)