README

Un package Laravel élégant et typé pour intégrer les APIs Mapbox (geocoding, search, directions) dans vos applications Laravel.

✨ Fonctionnalités

• 🎯 API typée - Auto-complétion complète et type safety
• 🚀 Fluent API - Interface intuitive
• 🔧 Configuration simple - Prêt à l'emploi en quelques minutes
• 📍 Support complet - Search Box API, Geocoding API
• ⚡ Laravel intégré - Service Provider, Facade, Configuration, Cache, Rate Limiting, Lock
• 🧪 Testé - Tests unitaires et d'intégration

📋 Prérequis

• PHP 8.1+
• Laravel 12.0+
• Token d'accès Mapbox

🚀 Installation

Installez le package via Composer :

composer require thomsult/laravel-mapbox

Publiez le fichier de configuration :

php artisan vendor:publish --provider="Thomsult\LaravelMapbox\Providers\MapboxServiceProvider" --tag="config"

Ajoutez votre token Mapbox dans votre fichier .env :

MAPBOX_ACCESS_TOKEN=votre_token_mapbox_ici

🔧 Configuration

Le fichier de configuration config/mapbox.php permet de personnaliser :

return [
    'access_token' => env('MAPBOX_ACCESS_TOKEN'),
    'base_uri' => 'https://api.mapbox.com/',
    'debug' => env('MAPBOX_DEBUG', false),
    'cache' => [
        'enabled' => env('MAPBOX_CACHE_ENABLED', true),
        'duration' => env('MAPBOX_CACHE_DURATION', 15),
        'timeout' => env('MAPBOX_CACHE_TIMEOUT', 5)
    ],
    'rate' => [
        'enabled' => env('MAPBOX_RATE_ENABLED', true),
        'limit' => env('MAPBOX_RATE_LIMIT', 60),
        'decay' => env('MAPBOX_RATE_DECAY', 60),
    ],
    'search' => [
        'api_version' => 'v1/',
        'prefix' => 'search/',
        'base_endpoint' => 'searchbox/',
        'forward_endpoint' => 'forward',
        'suggest_endpoint' => 'suggest',
        'retrieve_endpoint' => 'retrieve',
        'category_endpoint' => 'category',
        'category_list_endpoint' => 'list/category',
        'reverse_endpoint' => 'reverse',
    ],
    'geocoding' => [
        'api_version' => 'v6/',
        'prefix' => 'search/',
        'base_endpoint' => 'geocode/',
        'forward_endpoint' => 'forward',
        'reverse_endpoint' => 'reverse',
        'batch_endpoint' => 'batch'
    ]
];

📖 Utilisation

Recherche de base

Artisan::command('mapbox:search {query}', function ($query) {
    $this->comment('Mapbox search command');

    $response = MapboxClient::client()
        ->autocomplete(fn($req) => $req
            ->query($query)
            ->options(fn($options) => $options
                ->types([PlaceType::PLACE->value])
                ->limit(2)
                ->country('FR')
                ->language('fr')))
        ->call();
});
dd($response); // Affiche la réponse de l'API

Recherche inversée

Artisan::command('mapbox:search:reverse {longitude} {latitude}', function (string $longitude, string $latitude) {
    $this->comment('Mapbox search command');
    $response = MapboxClient::client()->reverse(
        fn($req) => $req
            ->longitude($longitude)
            ->latitude($latitude)
            ->options(
                fn($options) => $options
                    ->language('fr')
            )
    )
        ->call();
    dd($response);
});

Recherche Groupée

Artisan::command('mapbox:geocoding:batch', function () {
    $this->comment('Mapbox search command');
    $response = MapboxClient::client()->batch(
        fn($req) => $req
            ->body(
                fn($body) => $body
                    ->add(
                        (new ForwardTextRequest())
                            ->query("1600 Pennsylvania Avenue NW, Washington, DC 20500, United States")
                            ->options(
                                fn($options) => $options
                                    ->types("address")
                                    ->bbox("-80, 35, -70, 40")
                                    ->limit(1)
                            )
                    )
                    ->add(
                        (new ForwardTextRequest())
                            ->query("1605 Pennsylvania Avenue NW, Washington, DC 20500, United States")
                            ->options(
                                fn($options) => $options
                                    ->types("address")
                                    ->bbox("-80, 35, -70, 40")
                                    ->limit(1)
                            )
                    )
            )
    )
        ->call();
});

Types de lieux disponibles

use Thomsult\LaravelMapbox\Enums\PlaceType;

    case COUNTRY = 'country';
    case REGION = 'region';
    case POSTCODE = 'postcode';
    case DISTRICT = 'district';
    case PLACE = 'place';
    case CITY = 'city';
    case LOCALITY = 'locality';
    case NEIGHBORHOOD = 'neighborhood';
    case STREET = 'street';
    case ADDRESS = 'address';
    case POI = 'poi';
    case CATEGORY = 'category';
    case UNKNOWN = 'unknown';

Utilisation dans des commandes Artisan

Artisan::command('mapbox:search {query}', function ($query) {
    $this->comment('Mapbox search command');

    $response = MapboxClient::client()
        ->autocomplete(fn($req) => $req
            ->query($query)
            ->options(fn($options) => $options
                ->types([PlaceType::PLACE->value])
                ->limit(2)
                ->country('FR')
                ->language('fr')))
        ->call();
});

🧪 Tests

Tests unitaires

composer test

🤝 Contribution

Les contributions sont les bienvenues ! Merci de :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité
3. Commiter vos changements
4. Pousser vers la branche
5. Créer une Pull Request

📄 Licence

Ce package est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

• Mapbox pour leur excellente API
• Laravel pour le framework
• La communauté open source

📞 Support

• 🐛 Signaler un bug
• 💡 Demander une fonctionnalité
• 📖 Documentation

Créé avec ❤️ par Sultan Thomas