156 lines
No EOL
3.6 KiB
Markdown
156 lines
No EOL
3.6 KiB
Markdown
# Development Guidelines
|
|
|
|
This document provides guidelines and instructions for developing and maintaining the Futtern project.
|
|
|
|
## Build/Configuration Instructions
|
|
|
|
### Environment Setup
|
|
|
|
1. **PHP Requirements**: The project requires PHP 8.4 or higher with the following extensions:
|
|
- ctype
|
|
- iconv
|
|
|
|
2. **Composer**: Install dependencies using Composer:
|
|
```bash
|
|
composer install
|
|
```
|
|
|
|
3. **Environment Configuration**: Copy `.env` to `.env.local` and adjust the settings as needed for your local environment.
|
|
|
|
### Development Server
|
|
|
|
Start the Symfony development server:
|
|
```bash
|
|
symfony server:start
|
|
```
|
|
|
|
### Building Assets
|
|
|
|
The project uses Tailwind CSS via the symfonycasts/tailwind-bundle:
|
|
```bash
|
|
# Install importmap assets
|
|
symfony console importmap:install
|
|
```
|
|
|
|
## Deployment
|
|
|
|
The project includes several deployment scripts:
|
|
|
|
1. **Prepare for Deployment**:
|
|
```bash
|
|
./deploy/prepare-deploy.sh
|
|
```
|
|
This script creates a clean copy of the application with only production dependencies.
|
|
|
|
2. **Local Deployment**:
|
|
```bash
|
|
./deploy/local-deploy.sh
|
|
```
|
|
This script deploys the application to a remote server, backing up the database and restarting the service.
|
|
|
|
3. **Update After Deployment**:
|
|
```bash
|
|
./deploy/update.sh
|
|
```
|
|
This script is run on the remote server to clear cache, warm up cache, and run database migrations.
|
|
|
|
## Testing Information
|
|
|
|
### Testing Framework
|
|
|
|
The project uses Pest PHP, a testing framework built on top of PHPUnit, for testing. Tests are organized into:
|
|
- **Feature Tests**: For testing controllers and API endpoints
|
|
- **Unit Tests**: For testing individual components
|
|
|
|
### Running Tests
|
|
|
|
Run all tests:
|
|
```bash
|
|
composer test
|
|
# or
|
|
./vendor/bin/pest
|
|
```
|
|
|
|
Run specific tests:
|
|
```bash
|
|
./vendor/bin/pest tests/Unit/ExampleTest.php
|
|
```
|
|
|
|
Run tests in parallel:
|
|
```bash
|
|
./vendor/bin/pest --parallel
|
|
```
|
|
|
|
### Creating Tests
|
|
|
|
1. **Unit Tests**: Create files in the `tests/Unit` directory.
|
|
2. **Feature Tests**:
|
|
- Controller tests: Create files in `tests/Feature/Controller`
|
|
- API tests: Create files in `tests/Feature/Api`
|
|
|
|
### Example Test
|
|
|
|
Here's a simple example of a Pest PHP test:
|
|
|
|
```php
|
|
<?php declare(strict_types=1);
|
|
|
|
test('example test', function (): void {
|
|
expect(true)->toBeTrue();
|
|
expect(1 + 1)->toBe(2);
|
|
expect('hello world')->toContain('world');
|
|
});
|
|
|
|
test('array operations', function (): void {
|
|
$array = [1, 2, 3];
|
|
|
|
expect($array)->toHaveCount(3);
|
|
expect($array)->toContain(2);
|
|
expect($array[0])->toBe(1);
|
|
});
|
|
```
|
|
|
|
### Test Base Classes
|
|
|
|
- `DbWebTest`: Base class for controller tests
|
|
- `DbApiTestCase`: Base class for API tests
|
|
|
|
## Code Quality and Style
|
|
|
|
### Code Style
|
|
|
|
The project uses Easy Coding Standard (ECS) for code style checking:
|
|
```bash
|
|
composer lint
|
|
# or
|
|
./vendor/bin/ecs --fix
|
|
```
|
|
|
|
The code style is defined in `ecs.php` and includes:
|
|
- Custom rules from `Lubiana\CodeQuality\LubiSetList::ECS`
|
|
- All classes should be declared as final
|
|
|
|
### Code Refactoring
|
|
|
|
The project uses Rector for automated code refactoring:
|
|
```bash
|
|
./vendor/bin/rector
|
|
```
|
|
|
|
The refactoring rules are defined in `rector.php` and include:
|
|
- Custom rules from `Lubiana\CodeQuality\LubiSetList::RECTOR`
|
|
- StaticClosureRector is skipped in the tests directory
|
|
|
|
### Development Workflow
|
|
|
|
1. Make changes to the code
|
|
2. Run tests to ensure functionality: `composer test`
|
|
3. Fix code style issues: `composer lint`
|
|
4. Commit and push changes
|
|
5. Deploy using the deployment scripts
|
|
|
|
## Debugging
|
|
|
|
- Use the Symfony Web Profiler in development mode
|
|
- Check logs in `var/log/`
|
|
- For API debugging, use the API Platform documentation at `/api` |