Schnelle API-Entwicklung mit Laravel und API-Plattform

Es ist die persönliche Meinung dieses Autors, dass mehr Menschen außerhalb des PHP-Bereichs wissen sollten über API-Plattform. Es ist eine Erstaunliches Es ist ein erstaunlicher Baukasten, mit dem Sie Ihre gesamte Webanwendungs-API innerhalb von 10 Minuten strukturieren können, und verfügt über eine schwindelerregende Anzahl von Funktionen, mit denen Sie die Authentifizierung innerhalb Ihrer Anwendung durch Änderung der Konfigurationsschalter umgestalten und handhaben können.

In diesem Artikel nehmen wir eine bestehende Laravel-Anwendung, die die Messages API von Vonage verwendet, und öffnen sie als Web-API unter verschiedenen Standards.

Was ist eine API-Plattform?

Ok, jetzt kommt der etwas verwirrende Teil: Die API-Plattform ist ein PHP-Framework, aber dieses Framework sitzt dann entweder auf Symfony oder Laravel (was auch andere Frameworks und Plattformen einschließt, die auf diesen Dingen aufgebaut sind, wie z.B. Drupal oder WinterCMS). Betrachten Sie es als eine Reihe von Konfigurationen und Attributen, die Sie Ihrer Datenbankmodellierung und Ihrem Konfigurationsordner hinzufügen können. Außerdem ist ein komplettes Web-Dashboard integriert, das für Tests mit API-Tools wie Postman und OpenAPI Standards.

Hochfahren einer bestehenden Laravel-Applikation

AKA. "Hier ist eine, die ich vorhin gemacht habe!" Wir werden eine Anwendung verwenden, die nur eine einzige Datenbankeinheit hat: die bescheidene ToDo, die ich in einem früheren Artikel kodiert habe. Außerdem verwendet sie die Vonage Messages API um den Textinhalt des ToDo an ein konfiguriertes Gerät zu senden, wenn eines der ToDo-Elemente abgehakt wird (wie eine Benachrichtigung). Da es sich um eine voll funktionsfähige Anwendung handelt, starten wir zunächst diese Anwendung, bevor wir ihr die API-Plattform hinzufügen.

TLDR; Sie finden den den Quellcode hier.

Voraussetzungen

• git

• PHP 8.3+

• Node 23+ & npm

• Komponist

• Ein Vonage Account

Einrichten der Webanwendung

1. Holen Sie das Repository auf Ihren Rechner: https://github.com/Vonage-Community/blog-messages_native_php

2. Abhängigkeiten installieren: composer install

3. Führen Sie Migrationen in der Befehlszeile aus: php artisan migrate

4. Führen Sie npm in der Kommandozeile aus: npm i

5. In der Befehlszeile starten Sie Vite mit npm run dev

6. Führen Sie in der Befehlszeile den Datenbank-Seeder aus, um einige Daten in unsere Anwendung zu übertragen: php artisan db:seed

7. Kopieren Sie das Beispiel .env um es zu einem Live .env in der Befehlszeile: cp .env.example .env

8. Fügen Sie Ihre Vonage-Anmeldedaten in die Datei .env Datei hinzu.

Diese Anwendung verwendet die Vonage Messages API, um eine SMS zu versenden, wenn die Aufgabe erledigt ist. Sie müssen also einen Vonage Account und dann eine Vonage Anwendung erstellen. Wählen Sie bei der Erstellung der Anwendung die Nachrichtenfunktionalität aus, füllen Sie die Webhooks-Felder mit Dummy-Daten und notieren Sie sich die application_id bei der Erstellung. Verschieben Sie die private.key die automatisch heruntergeladen wird, in das Stammverzeichnis der Dateien Ihres Projekts.

In der Datei .env Datei müssen Sie Ihre Konfiguration hinzufügen:

VONAGE_APPLICATION_ID="<YOUR_APPLICATION_ID_HERE>"
VONAGE_PRIVATE_KEY_PATH="./private.key"
VONAGE_TO="<YOUR-NUMBER-HERE>"

Beachten Sie, dass VONAGE_PRIVATE_KEY_PATH immer den oben angegebenen Wert haben sollte, da die Anwendung Ihren privaten Schlüssel auf der Stammebene einlesen wird.

VONAGE_TO ist die Nummer, an die die SMS-Benachrichtigung gehen soll.

Sie müssen Ihre Anwendung bereitstellen. Ich empfehle die Verwendung von Laravel Herd. Sie finden die Installationsanleitung finden Sie hier. Alternativ können Sie den integrierten PHP-Server über die Befehlszeile ausführen: php artisan serve

App up and running!

Das Rätsel: MVC zu API

Die Anwendung ist als klassische Model-View-Controller-Anwendung mit einem Hauch von Frontend-Magie dank Laravel Livewire geschrieben. Betrachten Sie jedoch zwei Szenarien:

1. Wir wollen externe Tools in unsere Anwendung einbinden, also müssen wir eine API bereitstellen.

2. Massenskalierung bedeutet, dass wir das Front- und Backend entkoppeln müssen, d. h. wir haben ein separates JavaScript-Framework wie Svelte oder Vue, das Daten verbraucht und an die exponierte API sendet.

Die unglaubliche Erfahrung der API-Plattform

Es ist Zeit, API Platform zu installieren. Öffnen Sie Ihr Terminal und fügen Sie Folgendes hinzu:

composer require api-platform/laravel

Schließen Sie die Installation mit der Konsole ab.

php artisan api-platform:install

Das war's mit der Installation. Sie glauben mir nicht? Rufen Sie die URL Ihres Projekts auf und fügen Sie /api:

We've certainly done -something-Wir haben ein Eloquent ORM-Modell, Todo. In der App sieht es so aus:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Todo extends Model
{
   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */

   protected $casts = [
       'completed' => 'boolean',
   ];
}

Sind Sie bereit? Der nächste Schritt wird alles verändern, und ich werde erklären, was danach passiert. Fügen Sie dieses Attribut hinzu:

<?php

namespace App\Models;

use ApiPlatform\Metadata\ApiResource;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

#[ApiResource]
class Todo extends Model
{
   use HasFactory;

   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */
   protected $casts = [
       'completed' => 'boolean',
   ];
}

OK, ich habe hinzugefügt #[ApiResource]. Und was bewirkt das? Aktualisiert die /api/ Dashboard:

An OpenAPI document renders our new magic APIÄh, OK? Haben wir jetzt also einen vollständigen Satz von REST-Routen? Ich denke, ich sollte das überprüfen. In der Datenbank haben wir 10 Fixtures, also schauen wir mal, was passiert, wenn ich HTTPie zum Abfeuern der GET{id} Endpunkt abrufe, um den Eintrag 5 zu erhalten (außerdem sollten Sie in der realen Welt niemals Ihre Primärschlüssel in Ihrer Datenbank offenlegen!)

Absolute cinema!Hm? Sie haben gerade... eine API für mich erstellt? Wie wäre es, wenn ich eine PATCH Anfrage zum Bearbeiten des Titels?

Suddenly, a wild REST API appearsGUT. Wir haben zwei Zeilen Code hinzugefügt, und wir haben eine API. Das ist ziemlich wild.

Tiefer eintauchen: API-Standards und Paginierung

Die aufmerksamen unter Ihnen haben vielleicht bemerkt, dass API Platform standardmäßig ein Datenstrukturmuster verwendet, wobei die Felder mit dem Namen @Kontext und @id. Aber warum sehen die Felder so aus?

Die Antwort ist, dass die API-Plattform standardmäßig das JSON-LD-Format (JSON For Linking Data). Wir sehen hier vielleicht nur eine Entität, aber wenn wir eine Beziehung von einer zu mehreren Entitäten hätten, würde API Platform die zurückgegebenen Ergebnisse automatisch für Sie verarbeiten. Fügen wir als Beispiel eine neue Entität namens SubTask. In Eloquent würde die Beziehung wie folgt aussehen:

   public function subtasks(): HasMany
   {
       return $this->hasMany(Subtask::class);
   }

Der Aufruf desselben Endpunkts würde eine Antwort wie die folgende liefern. Beachten Sie, dass ich den Gruppen-Serialisierungscode hinzugefügt habe, der bestimmt, welche Felder wiedergegeben werden sollen. Mehr über die Serialisierung der API-Plattform erfahren Sie hieroder, speziell für Laravel, verwenden Sie die $visible Array-Konfiguration, um die zu rendernden Teile des Modells freizulegen.

{
    "@context": "/api/contexts/Todo",
    "@id": "/api/todos/5",
    "@type": "Todo",
    "id": 5,
    "title": "sample patch request",
    "completed": false,
    "createdAt": "2026-03-10T13:44:23+00:00",
    "updatedAt": "2026-03-11T11:41:13+00:00",
    "subTasks": [
        {
            "@id": "/api/sub_tasks/1",
            "@type": "SubTask",
            "id": 1,
            "title": "Write request body",
            "completed": true
        },
        {
            "@id": "/api/sub_tasks/2",
            "@type": "SubTask",
            "id": 2,
            "title": "Send PATCH request",
            "completed": false
        },
        {
            "@id": "/api/sub_tasks/3",
            "@type": "SubTask",
            "id": 3,
            "title": "Verify API response",
            "completed": false
        }
    ]
}

Wie cool ist das, wenn API Platform sich um Ihre API-Daten kümmert? Sieht so aus, als wäre es an der Zeit, all diese Transformationsschichten und DTOs loszuwerden!

Aber Moment mal: Was ist, wenn der Standard meiner Wahl für die REST-Entwicklung nicht JSON-LD ist? In diesem Fall wenden wir uns der Konfiguration zu, die Sie in configuration/api-platform.php.

<?php

/*
* This file is part of the API Platform project.
*
* (c) Kévin Dunglas <dunglas@gmail.com>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

declare(strict_types=1);

use ApiPlatform\Metadata\UrlGeneratorInterface;
use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Symfony\Component\Serializer\NameConverter\SnakeCaseToCamelCaseNameConverter;

return [
   'title' => 'API Platform',
   'description' => 'My awesome API',
   'version' => '1.0.0',
   'show_webby' => true,
   'routes' => [
       'domain' => null,
       // Global middleware applied to every API Platform routes
       // 'middleware' => [],
   ],
   'resources' => [
       app_path('Models'),
   ],
   'formats' => [
       'jsonld' => ['application/ld+json'],
       // 'jsonapi' => ['application/vnd.api+json'],
       // 'csv' => ['text/csv'],
   ],

(Ich habe das Copyright nur deshalb drin gelassen, damit Kevin Duglas ein Lob auszusprechen).

Aha! Sie sehen, es gibt einen formats Schlüssel im config-Array? Ändern wir das:

   'formats' => [
       'jsonld' => ['application/ld+json'],
       'jsonhal' => ['application/hal+json'],
   ],

Wenn Sie die Anfrage erneut senden, ändert sich nichts. Sie ist immer noch in JSON-LD. Warum?

Dies ist Teil der Implementierung der Inhaltsaushandlung der API-Plattform. LD-JSON ist immer noch die erste Schlüssel aufgeführt, was ihn zum Standard macht. Ändern Sie jedoch die Kopfzeilen Ihrer Anfrage in accept: application/hal+json und senden Sie die Anfrage ab:

Suddenly, a wild HAL appearsJetzt liegt die Macht in den Händen Ihrer API-Kunden, da sie das gewünschte Format anfordern können.

Es gibt Ihnen, dem Autor Ihrer API, auch die Möglichkeit, einen neuen Endpunkt in ihrer Anwendung zu erstellen, z. B. /api/v2, und einfach ändern. Machen wir uns nichts vor: Was ist, wenn wir unsere API einfach in eine GraphQL-API umwandeln wollen? Genau. Das können Sie in nur 3 Schritten!

1. Installieren Sie die API-Plattform GraphQL mit Composer im Browser

composer require api-platform/graphql

1. Aktivieren Sie GraphQL in Ihrer configuration/api-platform.php Datei

   'graphql' => [
       'enabled' => true,
       'nesting_separator' => '__',
       'introspection' => ['enabled' => true],
       'max_query_complexity' => 500,
       'max_query_depth' => 200,
       // 'middleware' => null,
   ],

1. Kopf nach /api/graphql und was passiert?

A Built-in GraphQL sandbox, just for youJa, das ist richtig. Sie haben einen GraphQL-Spielplatz, weil Ihre API jetzt GraphQL ist. Wenn Sie mir nicht glauben:

From REST to GraphQL in mere minutesSie haben jetzt eine GraphQL-API und eine REST-API.

Die Paginierung gehört zu den Dingen, die ich immer als sehr mühsam empfunden habe, um sie manuell zu implementieren. API Platform verfolgt hier einen Ansatz, der an Lächerlichkeit grenzt, wenn es darum geht, den Prozess der Integration der Paginierung zu vereinfachen. Betrachten Sie noch einmal unser ToDo-Modell:

<?php

namespace App\Models;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Symfony\Component\Serializer\Attribute\Groups;

#[ApiResource(normalizationContext: ['groups' => ['read']])]
#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
class Todo extends Model
{
   use HasFactory;

   /**
    * Get the subtasks for the todo.
    */
   #[ApiProperty(readableLink: true)]
   #[Groups(['read'])]
   public function subtasks(): HasMany
   {
       return $this->hasMany(Subtask::class);
   }

   /**
    * The attributes that are mass assignable.
    *
    * @var array<int, string>
    */

   protected $fillable = [
       'title',
       'completed',
   ];

   /**
    * The attributes that should be cast.
    *
    * @var array<string, string>
    */
   protected $casts = [
       'completed' => 'boolean',
   ];
}

Ich habe neue Attribute hinzugefügt, die der Formatierung der Subtask Beziehung dienen. Um eine Paginierung hinzuzufügen, werde ich einen Standardwert für die Anzahl der Entitäten festlegen, die pro Seite zurückgegeben werden, und dann den page URL-Abfragezeichenfolge. Fügen Sie der Klasse das folgende Attribut hinzu:

#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
#[ApiResource(
   normalizationContext: ['groups' => ['read']],
   paginationItemsPerPage: 5,
)]
#[ApiProperty(property: 'title', serialize: [new Groups(['read'])])]
#[ApiProperty(property: 'completed', serialize: [new Groups(['read'])])]
class Todo extends Model

Und das war's. Erledigt. Da wir 10 Todos haben, bedeutet das, dass wir zwei Seiten haben sollten - 5 Entitäten pro Seite. Sie können also testen, ob Sie Seite 2 hinzufügen können:

Magical pagination out of the boxAußerdem wurden magische Paginierungslinks hinzugefügt.

Schlussfolgerung

Einer der Punkte, die ich in meinem Vortrag über die Leistungsfähigkeit von API Platform auf der API Platform Conference 2025 angesprochen habe, war, dass PHP-Entwickler, die dieses Framework tagtäglich verwenden, wahrscheinlich nicht wissen, wie selten diese Art von Leistungsfähigkeit ist. Ich habe noch nie etwas anderes gesehen, das Entwicklern diese Art von Funktionen zur Verfügung stellt und sie so einfach macht. Wenn Sie nicht aus der PHP-Welt kommen, sollten Sie es ausprobieren - damit hat die API-Entwicklung für mich wieder Spaß gemacht.