v1.5.1

Contributing to Layup

Thanks for your interest in contributing! Here's how to get started.

Development Setup

# Clone the repo
git clone https://github.com/Crumbls/layup.git
cd layup

# Install dependencies
composer install

# Run tests
vendor/bin/pest

# Run code style fixer
vendor/bin/pint

# Run static analysis / refactoring
vendor/bin/rector --dry-run

Code Style

Layup uses Laravel Pint with the Laravel preset. Run it before committing:

vendor/bin/pint

The pre-push hook runs Pint in --test mode and Pest automatically. If either fails, the push is blocked.

Running Tests

# All tests
vendor/bin/pest

# Specific file
vendor/bin/pest tests/Unit/WidgetTest.php

# Filter by name
vendor/bin/pest --filter="renders heading widget"

# Parallel (faster)
vendor/bin/pest --parallel

Writing Tests

Tests live in tests/Unit/ and tests/Feature/. We use Pest.

Widget tests should cover:

  • Default data structure
  • Form schema returns valid Filament components
  • Preview renders something useful
  • Frontend rendering produces correct HTML
  • Edge cases (empty data, missing fields, long content)

Feature tests should cover:

  • Artisan commands
  • HTTP routes (frontend rendering)
  • Full page builder lifecycle

Example widget test:

it('renders with default data', function () {
    $widget = new MyWidget(['data' => MyWidget::getDefaultData()]);
    $html = $widget->render()->render();

    expect($html)->toBeString()->not->toBeEmpty();
});

it('has valid form schema', function () {
    $schema = MyWidget::getContentFormSchema();

    expect($schema)->toBeArray()->not->toBeEmpty();
    expect($schema[0])->toBeInstanceOf(\Filament\Forms\Components\Component::class);
});

Building Custom Widgets

See the Custom Widgets section in the README. The short version:

  1. Extend Crumbls\Layup\View\BaseWidget
  2. Implement getType(), getLabel(), getContentFormSchema(), getDefaultData(), render()
  3. Drop it in App\Layup\Widgets (auto-discovered) or register via config/plugin

If you're building a widget package for others to use, publish it as a Composer package with a service provider that registers the widgets.

Pull Requests

  1. Fork the repo and create a feature branch
  2. Write tests for your changes
  3. Run vendor/bin/pint and vendor/bin/pest
  4. Open a PR with a clear description of what and why

Keep PRs focused — one feature or fix per PR. Large refactors should be discussed in an issue first.

Reporting Issues

Open an issue with:

  • What you expected to happen
  • What actually happened
  • Steps to reproduce (minimal example)
  • PHP, Laravel, and Filament versions