Creating a PHP Service Library with Composer for a Map Service

I argue that modern PHP has entered the engineering stage. While early PHP development emphasized speed, larger projects now require engineering practices and scalability, often leading to micro‑service architectures.

In a recent project I needed a map service with its own database and API. Instead of using heavy network‑protocol solutions such as Thrift or HTTP, I chose to build a PHP "service library" using Composer.

Composer modifications

First, I separated the service library from the main application (xxx/main1) by creating a new Git repository named xxx/mapService.

In the main project's composer.json I added:

{
  "require": {
    "xxx/mapService": "dev-master"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "[email protected]:cloud/mapService.git"
    }
  ]
}

In the xxx/mapService repository the composer.json looks like:

{
  "description": "xxxxxx",
  "name": "xxx/mapService",
  "type": "library",
  "authors": [
    {
      "name": "Yejianfeng",
      "email": "[email protected]"
    }
  ],
  "require": {
    "php": ">=5.2.4",
    "illuminate/database": "*"
  },
  "autoload": {
    "psr-4": {
      "xxxx\\xxxx\\MapService\\": "src"
    }
  }
}

This configuration tells the main project where to fetch the mapService library and which version to use. Notes:

"dev-master" points to the master branch; you can replace it with a tag.

"repositories" defines the Git address.

The library resides on an internal GitLab instance.

The src folder uses the PSR‑4 namespace xxxx\xxxx\MapService\ .

The library depends on illuminate/database .

Running composer update -vvv downloads the library into the vendor directory.

Updating the library

When editing the service inside the main project, you can go to vendor/xxx/mapService and perform Git operations directly to push changes back to the library's master branch.

Independent configuration

To keep the service independent, configuration files should not rely on the main application. One approach is to create a dedicated Config class inside the service, although this embeds configuration in the Git repository. Laravel's ServiceProvider can place config files in Laravel's config folder, but that is not generic.

Directory structure

The service follows this layout (illustrated by the image in the original article):

Configs – configuration files

Contracts – interface definitions

Exceptions – custom exception classes

Supports – third‑party helpers or libraries

Models – database interaction

Node.php – concrete implementation

Example interface

interface NodeInterface {
    /*
     * Get nodes within a certain distance of a coordinate in a city.
     * @params int $cityId   City ID
     * @params int $lat      Latitude
     * @params int $lng      Longitude
     * @params int $distance Distance in meters
     * @return array(Models/Node)
     * @throws
     */
    public function gets($cityId, $lat, $lng, $distance);
}

Exceptions should be custom rather than error codes to allow unified handling at higher layers.

Thoughts

This architecture is a PHP‑centric service‑oriented pattern, suitable for scenarios where early development favors rapid delivery but later phases require formal serviceization.

Comparison with Git SubTree/SubModule

SubTree and SubModule are Git‑level solutions for embedding one repository in another. Composer, on the other hand, is a PHP‑level solution that also handles versioning and dependency resolution, making it a better fit for PHP projects.

Future protocol service

If the mapService later needs to become a protocol‑based service, it can be turned into an SDK and updated via composer update .

Service registration and discovery

The current "service library" does not address registration or discovery; additional mechanisms would be required to track which projects consume the service.