06 — Contributing

Back to README | Prev: Roadmap

Getting Started

Prerequisites

• PHP 8.2+
• Composer
• Node.js 18+ & npm
• SQLite (for local development) or MySQL/PostgreSQL

Local Setup

# Clone the repository
git clone <repo-url> LaraSchema
cd LaraSchema

# Install PHP dependencies (includes the package via path repository)
composer install

# Set up environment
cp .env.example .env
php artisan key:generate

# Run migrations (creates the 5 laraschema_* tables)
php artisan migrate

# Install and build frontend assets
npm install
npm run dev

# Start the dev server
php artisan serve

Visit http://localhost:8000/laraschema to verify everything works.

Project Structure

Understanding where things live:

LaraSchema/
├── packages/laraschema/     <- THE PACKAGE (most work happens here)
│   ├── src/                  <- PHP source code
│   │   ├── Http/Livewire/    <- Livewire components (Canvas, TableEditor, etc.)
│   │   ├── Models/           <- Eloquent models
│   │   ├── Enums/            <- ColumnType, RelationshipType
│   │   ├── Generators/       <- Code generation (MigrationGenerator)
│   │   └── Services/         <- Business logic services
│   ├── resources/views/      <- Blade templates + inline Alpine.js
│   ├── config/               <- Package config
│   ├── database/migrations/  <- Package migrations
│   └── routes/               <- Package routes
│
├── app/                      <- Host Laravel app (minimal — mostly for SaaS features)
├── docs/                     <- Documentation (you're reading it)
└── tests/                    <- Test suite

Key principle: Almost all code goes in packages/laraschema/. The host app is a thin wrapper.

Coding Conventions

PHP

• PHP 8.2+ — use typed properties, enums, match expressions, named arguments
• PSR-12 coding style
• Strict types — add declare(strict_types=1); to all PHP files
• Type hints — all method parameters and return types must be typed
• Models — use $casts array, define all relationships explicitly
• No abbreviations — $relationship not $rel, $column not $col

Livewire Components

• One component per file, matching the view name
• Use #[Layout('laraschema::layouts.app')] attribute for layout
• Validate all user input before persisting
• Dispatch events for cross-component communication (e.g., table-updated)
• Use wire:model.blur instead of wire:model.live for text inputs (reduces server calls)

Alpine.js

• All Alpine code is inline in Blade views (no separate JS files in the package)
• Use x-data="componentName(...)" pattern with a named function
• Keep Alpine state minimal — derive values with getters where possible
• Use $wire for Livewire communication, $dispatch for Alpine-to-Alpine

Blade Views

• Views are namespaced as laraschema:: (e.g., laraschema::livewire.canvas)
• Use Tailwind CSS utility classes exclusively — no custom CSS
• Prefer Alpine.js directives over inline JavaScript

Database

• All package tables use laraschema_ prefix
• Use foreign key constraints with cascadeOnDelete()
• JSON columns for flexible/variable-shape data
• Soft deletes only on projects table

Naming

Git Workflow

Branch Naming

feature/short-description     <- New features
fix/short-description         <- Bug fixes
docs/short-description        <- Documentation changes
refactor/short-description    <- Code refactoring

Commit Messages

Use conventional commit format:

feat: add column reordering to table editor
fix: prevent duplicate table names in same project
docs: update architecture diagram
refactor: extract migration generation into service
test: add tests for MigrationGenerator

Pull Request Process

1. Create a feature branch from main
2. Make your changes in small, focused commits
3. Ensure all tests pass: php artisan test
4. Ensure code style is correct: ./vendor/bin/pint
5. Open a PR with:
   • Clear description of what changed and why
   • Screenshots for UI changes
   • Test plan

Testing

Running Tests

# Run all tests
php artisan test

# Run specific test file
php artisan test --filter=MigrationGeneratorTest

# Run with coverage
php artisan test --coverage

Test Organization

tests/
├── Feature/
│   ├── ProjectManagerTest.php
│   ├── CanvasTest.php
│   └── ExportTest.php
└── Unit/
    ├── MigrationGeneratorTest.php
    ├── ColumnTypeTest.php
    └── Models/
        └── ProjectTest.php

What to Test

• Models: Relationships, casts, scopes
• Livewire components: User interactions, validation, state changes
• Generators: Output correctness for all column types and relationships
• Services: Business logic in isolation

Key Documents

If you're new to the project, read these in order:

1. Project Overview — What we're building and why
2. Architecture — How the system is designed
3. Database Design — Data model and schema
4. Phase 1 Implementation — Current build plan
5. Roadmap — What's coming next

Questions?

If something in the codebase or docs is unclear, open an issue or ask in the team channel. Good documentation benefits everyone — if you figure something out that wasn't documented, please add it.