Expanded and reorganized README with detailed setup, stack, and environment information.
This commit is contained in:
@@ -1,66 +1,172 @@
|
|||||||
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
|
# FilamentLaravel
|
||||||
|
|
||||||
<p align="center">
|
A Laravel 12 application scaffolded with Jetstream and Livewire, built with Vite and Tailwind CSS. This repo includes common local‑dev conveniences (concurrent processes for PHP server, queue worker, logs, and Vite) and a modern testing setup using Pest.
|
||||||
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
|
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
|
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
|
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
## About Laravel
|
If you’re new to this codebase, this README helps you get it running locally and understand where things live.
|
||||||
|
|
||||||
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
|
> Note: The project name in `.env` is `APP_NAME=FilamentApp`. The repository name is `FilamentLaravel`.
|
||||||
|
|
||||||
- [Simple, fast routing engine](https://laravel.com/docs/routing).
|
## Stack
|
||||||
- [Powerful dependency injection container](https://laravel.com/docs/container).
|
|
||||||
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
|
|
||||||
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
|
|
||||||
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
|
|
||||||
- [Robust background job processing](https://laravel.com/docs/queues).
|
|
||||||
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
|
|
||||||
|
|
||||||
Laravel is accessible, powerful, and provides tools required for large, robust applications.
|
- Language: PHP ^8.2
|
||||||
|
- Framework: Laravel ^12.0
|
||||||
|
- Jetstream ^5.3
|
||||||
|
- Sanctum ^4.0
|
||||||
|
- Livewire ^3.x and Livewire Flux ^2.x
|
||||||
|
- Frontend tooling: Vite ^6, Tailwind CSS ^4, PostCSS
|
||||||
|
- Package managers: Composer (PHP), npm (Node)
|
||||||
|
- Testing: Pest ^3 (with PHPUnit under the hood)
|
||||||
|
|
||||||
## Learning Laravel
|
## Requirements
|
||||||
|
|
||||||
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.
|
- PHP 8.2+
|
||||||
|
- Composer 2.x
|
||||||
|
- Node.js 18+ and npm 9+
|
||||||
|
- A database (MySQL/MariaDB). Defaults from `.env`:
|
||||||
|
- `DB_HOST=127.0.0.1`, `DB_PORT=3306`, `DB_DATABASE=filamentlaravel`, `DB_USERNAME=root`, `DB_PASSWORD=ServBay.dev`
|
||||||
|
- Optional services depending on features you use:
|
||||||
|
- Redis (default client configured: `phpredis`)
|
||||||
|
- Mail catcher or SMTP server (defaults to `MAIL_MAILER=log`)
|
||||||
|
|
||||||
You may also try the [Laravel Bootcamp](https://bootcamp.laravel.com), where you will be guided through building a modern Laravel application from scratch.
|
## Quick start
|
||||||
|
|
||||||
If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
|
1. Clone and install dependencies
|
||||||
|
```bash
|
||||||
|
git clone <your-fork-or-repo-url>
|
||||||
|
cd FilamentLaravel
|
||||||
|
composer install
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
2. Configure environment
|
||||||
|
```bash
|
||||||
|
cp .env.example .env # if .env doesn’t exist
|
||||||
|
php artisan key:generate
|
||||||
|
```
|
||||||
|
- Update `.env` database credentials as needed.
|
||||||
|
- Ensure `SESSION_DRIVER=database` (already set) and run migrations (next step) to create the sessions table.
|
||||||
|
3. Create database and run migrations
|
||||||
|
```bash
|
||||||
|
php artisan migrate
|
||||||
|
```
|
||||||
|
4. Run the app (all-in-one dev experience)
|
||||||
|
```bash
|
||||||
|
composer run dev
|
||||||
|
```
|
||||||
|
This starts:
|
||||||
|
- `php artisan serve` (Laravel app)
|
||||||
|
- `php artisan queue:listen --tries=1` (queue worker)
|
||||||
|
- `php artisan pail --timeout=0` (pretty app logs)
|
||||||
|
- `npm run dev` (Vite)
|
||||||
|
|
||||||
## Laravel Sponsors
|
Or run them individually:
|
||||||
|
```bash
|
||||||
|
php artisan serve
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
|
5. Visit the app at the URL shown by `php artisan serve` (defaults to `http://127.0.0.1:8000`). You can also set `APP_URL` in `.env`.
|
||||||
|
|
||||||
### Premium Partners
|
## Scripts
|
||||||
|
|
||||||
- **[Vehikl](https://vehikl.com/)**
|
- Composer
|
||||||
- **[Tighten Co.](https://tighten.co)**
|
- `composer run dev` — concurrently run server, queue worker, logs, and Vite
|
||||||
- **[WebReinvent](https://webreinvent.com/)**
|
- npm
|
||||||
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
|
- `npm run dev` — start Vite in dev mode
|
||||||
- **[64 Robots](https://64robots.com)**
|
- `npm run build` — build frontend assets for production
|
||||||
- **[Curotec](https://www.curotec.com/services/technologies/laravel/)**
|
|
||||||
- **[Cyber-Duck](https://cyber-duck.co.uk)**
|
|
||||||
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
|
|
||||||
- **[Jump24](https://jump24.co.uk)**
|
|
||||||
- **[Redberry](https://redberry.international/laravel/)**
|
|
||||||
- **[Active Logic](https://activelogic.com)**
|
|
||||||
- **[byte5](https://byte5.de)**
|
|
||||||
- **[OP.GG](https://op.gg)**
|
|
||||||
|
|
||||||
## Contributing
|
## Environment variables
|
||||||
|
|
||||||
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
|
See `.env` for all variables. Common ones:
|
||||||
|
|
||||||
## Code of Conduct
|
- Application
|
||||||
|
- `APP_NAME` (default: `FilamentApp`)
|
||||||
|
- `APP_ENV` (`local`, `production`, ...)
|
||||||
|
- `APP_DEBUG` (true/false)
|
||||||
|
- `APP_URL` (default: `http://localhost`)
|
||||||
|
- `APP_LOCALE`, `APP_FALLBACK_LOCALE`
|
||||||
|
- Logging
|
||||||
|
- `LOG_CHANNEL` (default: `stack`), `LOG_LEVEL`
|
||||||
|
- Database (MySQL by default)
|
||||||
|
- `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
|
||||||
|
- Cache/Queue/Session
|
||||||
|
- `CACHE_STORE=database`
|
||||||
|
- `QUEUE_CONNECTION=database`
|
||||||
|
- `SESSION_DRIVER=database`, `SESSION_LIFETIME`
|
||||||
|
- Redis
|
||||||
|
- `REDIS_CLIENT=phpredis`, `REDIS_HOST`, `REDIS_PORT`
|
||||||
|
- Mail
|
||||||
|
- `MAIL_MAILER=log`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM_*`
|
||||||
|
- AWS (only if you enable S3, etc.)
|
||||||
|
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET`
|
||||||
|
- Vite
|
||||||
|
- `VITE_APP_NAME` (default mirrors `APP_NAME`)
|
||||||
|
|
||||||
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
|
## Project structure (selected)
|
||||||
|
|
||||||
## Security Vulnerabilities
|
- `app/` — application code (models, controllers, policies, jobs, etc.)
|
||||||
|
- `bootstrap/` — framework bootstrap files
|
||||||
|
- `config/` — application configuration
|
||||||
|
- `database/` — migrations, factories, seeders
|
||||||
|
- `public/` — public web root (entry: `public/index.php`)
|
||||||
|
- `resources/` — Blade views, CSS, JS
|
||||||
|
- `resources/css/app.css` — Tailwind entry
|
||||||
|
- `resources/js/app.js` — JS entry (referenced by Vite)
|
||||||
|
- `resources/views/...` — Blade templates (includes Livewire components)
|
||||||
|
- `routes/`
|
||||||
|
- `web.php` — web routes
|
||||||
|
- `api.php` — API routes
|
||||||
|
- `tests/` — test suite (Pest)
|
||||||
|
- `vite.config.js` — Vite configuration
|
||||||
|
- `artisan` — Laravel CLI
|
||||||
|
- `composer.json` / `package.json` — dependencies and scripts
|
||||||
|
|
||||||
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
|
## Development notes
|
||||||
|
|
||||||
|
- Vite HMR refresh is enabled via `laravel-vite-plugin` with inputs `resources/css/app.css` and `resources/js/app.js`.
|
||||||
|
- Sessions, cache, and queue default to database-backed stores. Ensure migrations are run.
|
||||||
|
- Jetstream is installed. The chosen Jetstream stack (Livewire vs Inertia) isn’t explicitly declared here — Livewire is present. See `composer.json` and `resources/views` for details.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Run the test suite:
|
||||||
|
```bash
|
||||||
|
php artisan test
|
||||||
|
# or
|
||||||
|
./vendor/bin/pest
|
||||||
|
```
|
||||||
|
|
||||||
|
You can create tests under `tests/` using Pest’s syntax.
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
- Build frontend assets:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
- Ensure `APP_ENV=production`, `APP_DEBUG=false`, correct `APP_URL`, and proper cache/queue/mail configurations.
|
||||||
|
- Run database migrations on deploy:
|
||||||
|
```bash
|
||||||
|
php artisan migrate --force
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker (optional)
|
||||||
|
Laravel Sail is included as a dev dependency. If you prefer Docker, you can set up Sail. This repository does not include a prepared Sail config in this README.
|
||||||
|
|
||||||
|
## Entry points
|
||||||
|
|
||||||
|
- HTTP: `public/index.php` (served via the web server or `php artisan serve`)
|
||||||
|
- CLI: `artisan`
|
||||||
|
- Frontend dev server: `npm run dev` (Vite)
|
||||||
|
|
||||||
|
## TODOs / Unknowns
|
||||||
|
|
||||||
|
- Production deployment target and steps (server, PaaS, container registry) — TODO
|
||||||
|
- Domain and HTTPS/TLS configuration — TODO
|
||||||
|
- Mail provider and credentials for non‑log mailers — TODO
|
||||||
|
- Storage driver(s) for user uploads (local vs S3) — TODO
|
||||||
|
- Background jobs in production (e.g., Supervisor, Horizon) — TODO
|
||||||
|
- Any seeded demo data or default admin user — TODO
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
|
This project is open-sourced software licensed under the MIT license. See `composer.json` for the declared license.
|
||||||
|
|||||||
Reference in New Issue
Block a user