amphibee/marius-api

Laravel package for Marius API integration

Maintainers

Details

github.com/AmphiBee/Marius-Api

Source

Issues

Installs: 156

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 2

Forks: 1

Open Issues: 1

1.0 2024-12-18 10:57 UTC

Requires

Requires (Dev)

MIT 2b9d50316e439dee06ec452a683d707515df58ee

This package is auto-updated.

Last update: 2024-12-18 10:59:08 UTC

README

A Laravel package for easy interaction with the Marius Application API.

📋 Table of Contents

🚀 Installation

Requirements

  • PHP 8.1 or higher
  • Laravel 9.0 or higher

Via Composer

composer require amphibee/marius-api

The package will be automatically discovered by Laravel. The following Facades will be registered:

  • Campus
  • Formation
  • Candidature

⚙️ Configuration

  1. Publish the configuration file:
php artisan vendor:publish --tag="marius-config"
  1. Configure your environment variables in your .env file:
MARIUS_API_BASE_URL=https://marius.website.com/api
MARIUS_API_KEY=your-api-key
MARIUS_API_TIMEOUT=10

📖 Usage

First, import the Facades you need:

use AmphiBee\MariusApi\Facades\Campus;
use AmphiBee\MariusApi\Facades\Formation;
use AmphiBee\MariusApi\Facades\Candidature;
use AmphiBee\MariusApi\Exceptions\MariusApiException;

Campus

Retrieve and manage campus information:

try {
    // Get all campuses with their courses
    $campuses = Campus::getCampuses();
    
    foreach ($campuses as $campus) {
        echo $campus->campus; // Campus name
        echo $campus->id_campus; // Campus ID
        
        // Access campus courses
        foreach ($campus->formations as $formation) {
            echo $formation->nom_formation;
            echo $formation->niveau_sortie;
        }
    }
} catch (MariusApiException $e) {
    // Handle API errors
    Log::error('Marius API Error: ' . $e->getMessage());
}

Courses

Manage course information by campus:

try {
    // Get courses for a specific campus
    $formations = Formation::getFormationsByCampus('1');
    
    foreach ($formations as $formation) {
        echo $formation->id_formation;
        echo $formation->nom_formation;
        echo $formation->niveau_sortie;
    }
} catch (MariusApiException $e) {
    // Handle API errors
}

Applications

Submit and manage student applications:

use AmphiBee\MariusApi\DTO\CandidatureDTO;

try {
    $application = new CandidatureDTO([
        'civilite' => 'Mr',
        'nom' => 'Doe',
        'prenom' => 'John',
        'email' => 'john@example.com',
        'portable' => '0612345678',
        'id_campus' => '1',
        'id_formation' => '30'
    ]);
    
    $response = Candidature::submit($application);
    // $response contains the API response with the application ID
    
} catch (MariusApiException $e) {
    // Handle API errors
}

Example in a Controller

Here's a complete example of using the Facades in a Laravel controller:

namespace App\Http\Controllers;

use AmphiBee\MariusApi\DTO\CandidatureDTO;
use AmphiBee\MariusApi\Exceptions\MariusApiException;
use AmphiBee\MariusApi\Facades\Campus as Campus;
use AmphiBee\MariusApi\Facades\Formation as Formation;
use AmphiBee\MariusApi\Facades\Candidature as Candidature;
use Illuminate\Http\Request;

class ApplicationController extends Controller
{
    public function index()
    {
        try {
            return view('application.form', [
                'campuses' => Campus::getCampuses()
            ]);
        } catch (MariusApiException $e) {
            return back()->withError($e->getMessage());
        }
    }

    public function getFormations(string $campusId)
    {
        try {
            return response()->json([
                'formations' => Formation::getFormationsByCampus($campusId)
            ]);
        } catch (MariusApiException $e) {
            return response()->json(['error' => $e->getMessage()], 422);
        }
    }

    public function submit(Request $request)
    {
        try {
            $application = new CandidatureDTO($request->validated());
            $response = Candidature::submit($application);
            
            return redirect()
                ->route('application.success')
                ->with('application_id', $response['id_candidature']);
                
        } catch (MariusApiException $e) {
            return back()
                ->withInput()
                ->withError($e->getMessage());
        }
    }
}

🧪 Testing

The package includes a comprehensive test suite. When testing your own application, you can mock the Facades:

use AmphiBee\MariusApi\Facades\Campus;
use AmphiBee\MariusApi\Facades\Formation;
use AmphiBee\MariusApi\Facades\Candidature;

it('can list all campuses', function () {
    // Arrange
    Campus::shouldReceive('getCampuses')
        ->once()
        ->andReturn([
            // Your mock data here
        ]);

    // Act
    $response = $this->get('/applications/create');

    // Assert
    $response->assertOk();
});

it('can get formations for campus', function () {
    // Arrange
    Formation::shouldReceive('getFormationsByCampus')
        ->with('1')
        ->once()
        ->andReturn([
            // Your mock data here
        ]);

    // Act
    $response = $this->get('/api/campus/1/formations');

    // Assert
    $response->assertOk();
});

❌ Error Handling

All Facade methods can throw MariusApiException. It's recommended to wrap calls in try-catch blocks:

use AmphiBee\MariusApi\Exceptions\MariusApiException;

try {
    $campuses = Campus::getCampuses();
} catch (MariusApiException $e) {
    // The error contains the message and HTTP code from the API error
    Log::error('Marius API Error: ' . $e->getMessage());
    // Handle the error appropriately
}

📚 Advanced Usage

Working with DTOs

The package uses Data Transfer Objects (DTOs) to ensure type safety and validation:

use AmphiBee\MariusApi\DTO\CandidatureDTO;

// Create from array
$application = new CandidatureDTO([
    'civilite' => 'Mr',
    'nom' => 'Doe',
    'prenom' => 'John',
    'email' => 'john@example.com',
    'portable' => '0612345678',
    'id_campus' => '1',
    'id_formation' => '30'
]);

// Create from request
$application = new CandidatureDTO($request->validated());

// Submit
$response = Candidature::submit($application);

Logging API Responses

The package includes built-in logging capabilities for debugging purposes. Each service provides a getRawResponse() method that returns the raw API response:

use AmphiBee\MariusApi\DTO\CandidatureDTO;
use Illuminate\Support\Facades\Log;

try {
    $application = new CandidatureDTO([
        'civilite' => 'Mr',
        'nom' => 'Doe',
        // ... autres données
    ]);
    
    $response = Candidature::submit($application);
    
    // Log the raw response
    Log::channel('api')->info('Marius API Response', [
        'response' => Candidature::getRawResponse()
    ]);
    
} catch (MariusApiException $e) {
    Log::channel('api')->error('Marius API Error', [
        'message' => $e->getMessage(),
        'trace' => $e->getTraceAsString()
    ]);
}

To enable API logging, add this to your config/logging.php:

'channels' => [
    // ... autres canaux
    
    'api' => [
        'driver' => 'daily',
        'path' => storage_path('logs/api.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 14,
    ],
],

The logs will be stored in storage/logs/api.log with this format:

[2024-03-14 10:30:00] local.INFO: Marius API - Données d'entrée {"data":{"civilite":"Mr","nom":"Doe",...}}
[2024-03-14 10:30:01] local.INFO: Marius API - Réponse {"response":{"id_candidature":"123",...}}

🧪 Testing

The package includes a comprehensive test suite using Pest. To run the tests:

./vendor/bin/pest

❌ Error Handling

The package uses a custom MariusApiException for error handling. All methods can throw this exception in case of API errors.

use AmphiBee\MariusApi\Exceptions\MariusApiException;

try {
    $campuses = $campusService->getCampuses();
} catch (MariusApiException $e) {
    // The error contains the message and HTTP code from the API error
    echo $e->getMessage();
}

🤝 Contributing

Contributions are welcome! Feel free to:

  1. Fork the project
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Make sure to update tests as appropriate.

Development Setup

  1. Clone the repository
  2. Install dependencies: composer install
  3. Run tests: ./vendor/bin/pest

Coding Standards

This package follows PSR-12 coding standards. Before submitting a PR, please ensure your code follows these standards by running:

composer fix-style

📄 License

This package is licensed under the MIT License. See the LICENSE file for details.

🏢 About AmphiBee

Developed and maintained by AmphiBee. For more information about our services or other open-source projects, please visit our website.

🔒 Security

If you discover any security-related issues, please email security@amphibee.fr instead of using the issue tracker.

⭐ Support

If you find this package helpful, please consider starring it on GitHub. For professional support or custom development needs, contact us at contact@amphibee.fr.

📚 Documentation

For detailed documentation of the Marius API itself, please refer to the official API documentation provided by your institution.

Additional Resources