WINCHHandbook
Get Started

Installation

This chapter takes a freshly cloned `winchsa/backend` checkout to a running application with a working queue worker, a passing test suite, and the git hooks installed. Budget about an hour the first time you do it; later setups on the same machine take ten minutes.

Prerequisites

We develop on macOS and Linux. The recommended local environment is Laravel Herd — it ships PHP, nginx, and a .test domain server pre-configured for Laravel. If you already have a working PHP 8.4 toolchain (FPM, Composer, MySQL or Postgres, Redis) you can skip Herd and use that instead.

You will also need:

  • MySQL 8 (or a compatible MariaDB) for the application database.
  • Redis for the cache, session, and queue backends.
  • Node 20+ for any frontend asset builds you may need to run.
  • Git, with your SSH key uploaded to GitHub so you can clone over SSH.

1. Clone the repository

git clone git@github.com:winchsa/backend.git
cd backend

If you cloned over HTTPS, switch the remote to SSH later or expect Composer to prompt for credentials when it pulls private packages.

2. Install PHP dependencies

composer install --ignore-platform-reqs

--ignore-platform-reqs is here because the project's composer.json pins extensions some setups don't have locally. Once your local PHP has every extension installed you can drop the flag.

3. Configure environment variables

cp .env.example .env
php artisan key:generate

Open .env and fill in the values that the example file leaves blank — database credentials, the Redis host, the Firebase service-account path, the AWS S3 credentials for the development bucket, and the Sentry DSN if you want errors reported. Ask a teammate for the development-tier secrets; never commit a populated .env.

If you are running on Herd, APP_URL should match the kebab-cased project directory, e.g. http://backend.test.

4. Create the database

Create an empty database matching DB_DATABASE in your .env, then run:

php artisan migrate:fresh --seed

The --seed flag loads the development seeders so you have realistic data to click through. The seeders are idempotent on a fresh database; they are not safe to re-run on a populated one.

5. Install the git hooks

./install-git-hooks.sh

The pre-push hook runs php artisan translations:check --changed — it validates that every translation key used in the files you're pushing is present in lang/en/ and lang/ar/. If the hook fails, add the missing keys and try the push again. Do not bypass with --no-verify; the alternative is broken UI in the other locale.

6. Start the queue worker

Most application flows dispatch jobs — order processing, notifications, exports. Without a worker, dispatched jobs sit in Redis and the UI silently waits for outcomes that never arrive.

php artisan queue:work

For local development with the Horizon dashboard:

php artisan horizon

Horizon supervises the workers and exposes a monitoring UI at /horizon. Stop and restart it after deploying changes to a job's handle() method — the worker has the old code cached otherwise.

7. Run the test suite

./vendor/bin/pest

Green suite confirms your local environment is wired up correctly. To filter by file:

./vendor/bin/pest tests/Unit
./vendor/bin/pest tests/Feature

The first run is slow because Pest compiles its test classes; subsequent runs are quick.

8. Run the formatter

./vendor/bin/pint

Laravel Pint enforces the project's PHP style. Run it before every commit — CI rejects diffs that Pint would change. Use --dirty to limit it to files you've modified since the last commit.

What to do next

Introduction

A short welcome and a map of what you'll find in this handbook before you write your first line of code.

Configuration

Set up the environment, database, cache, queue, and server bits the application needs to boot.