README

Experiment-agnostic office location retrieval SDK for PHP 8.2+.

Overview

locations-service provides a stable, reusable API for querying office locations and their usage attributes across GLANCE deployments. It is designed as a layered library with strict domain modeling and an SQL adapter based on Doctrine DBAL.

The package exposes one application entry point, LocationsProvider, which supports:

• listing by experiment
• listing by current-use code
• lookup by location id
• lookup by exact address
• fuzzy search by address fragment

Etymology

The name reflects its role in the GLANCE ecosystem: a dedicated service-style library that encapsulates location domain logic and infrastructure concerns behind a compact provider API.

Stack

Architecture follows the same Domain / Application / Infrastructure layering used in the ALICE GLANCE suite:

src/
├── Domain/                    # Value objects, entity, repository contract, exceptions
│   ├── Exception/
│   ├── Address.php
│   ├── Capacity.php
│   ├── CurrentUse.php
│   ├── Experiment.php
│   ├── FloorType.php
│   ├── Height.php
│   ├── IntendedUse.php
│   ├── IntegerId.php
│   ├── Location.php
│   ├── LocationId.php
│   ├── LocationRepository.php
│   ├── PersonId.php
│   ├── PhysicalCharacteristics.php
│   ├── SurfaceArea.php
│   └── Usage.php
├── Application/               # Use-case oriented query facade
│   └── LocationsProvider.php
└── Infrastructure/            # Driver config, factory, DI bindings, SQL adapter
	├── LocationsProviderConfig.php
	├── LocationsProviderFactory.php
	├── LocationsServiceDependencies.php
	└── Sql/
		├── SqlLocation.php
		├── SqlLocationsProviderConfig.php
		└── SqlLocationsRepository.php

Installation

composer require glance-project/locations-service

Usage

Standalone

use Glance\LocationsService\Application\LocationsProvider;
use Glance\LocationsService\Domain\Experiment;
use Glance\LocationsService\Infrastructure\LocationsProviderFactory;
use Glance\LocationsService\Infrastructure\Sql\SqlLocationsProviderConfig;

$config = SqlLocationsProviderConfig::create(
	username: 'my-user',
	password: 'my-password',
	dns: 'MY_ORACLE_SERVICE'
);

$factory = LocationsProviderFactory::create();
$provider = $factory->getInstance($config);

$aliceLocations = $provider->listLocationsByExperiment(Experiment::alice());
$atlasLocations = $provider->listLocationsByExperiment(Experiment::atlas());
$lhcbLocations = $provider->listLocationsByExperiment(Experiment::lhcb());
$cmsLocations = $provider->listLocationsByExperiment(Experiment::cms());

With a PSR-11 DI Container (php-di)

use DI\ContainerBuilder;
use Glance\LocationsService\Application\LocationsProvider;
use Glance\LocationsService\Infrastructure\LocationsProviderConfig;
use Glance\LocationsService\Infrastructure\LocationsServiceDependencies;
use Glance\LocationsService\Infrastructure\Sql\SqlLocationsProviderConfig;

$builder = new ContainerBuilder();

// Default package bindings (configuration from environment variables).
$builder->addDefinitions(LocationsServiceDependencies::definitions());

// Optional override to control config source.
$builder->addDefinitions([
	LocationsProviderConfig::class => static fn(): SqlLocationsProviderConfig =>
		SqlLocationsProviderConfig::fromArray([
			'username' => $_ENV['LOCATIONS_DB_USERNAME'] ?? 'user',
			'password' => $_ENV['LOCATIONS_DB_PASSWORD'] ?? 'password',
			'dns' => $_ENV['LOCATIONS_DB_DSN'] ?? 'MY_ORACLE_SERVICE',
		]),
]);

$container = $builder->build();
$provider = $container->get(LocationsProvider::class);

LocationsServiceDependencies::definitions() returns plain closure factories and remains compatible with any PSR-11 container workflow.

Locations Data

The service retrieves location data from CERN's central office locations database. Visit their documentation for details on the data model and maintenance. This SDK is designed to be resilient to changes in the underlying database schema, but breaking changes may require updates to the SQL adapter layer.

You may need to coordinate with the locations database administrators to ensure your database user has the necessary permissions to access the relevant views and that any schema changes are communicated in advance.

Environment Variables

The SQL adapter configuration can be provided through environment variables:

• LOCATIONS_DB_USERNAME: Database username that has read access to the locations views
• LOCATIONS_DB_PASSWORD: Database password for the above user
• LOCATIONS_DB_DSN: Database DSN (e.g., cerndb1) for the Oracle service hosting the locations database

SQL Model

The SQL adapter joins two views under schema AISPUB:

• LOC_CL_CUR_LOCAL_INFO: physical attributes
• LOC_CL_CUR_GESLOC_ROOMS: usage attributes

Selected columns are mapped through SqlLocation into the domain aggregate Location.

Make sure the database user has read access to these views and that the column names match the expected schema for correct mapping.

Domain Model

Location Aggregate root representing one office location, composed of:

• LocationId id
• PhysicalCharacteristics physicalCharacteristics
• Usage usage

PhysicalCharacteristics Immutable value object containing location physical data:

• Address address
• IntendedUse intendedUse
• ?string comment
• ?Height height
• SurfaceArea surfaceArea
• ?SurfaceArea windowSurfaceArea
• ?FloorType floorType

Usage Immutable value object containing occupancy/organizational data:

• Experiment experiment
• CurrentUse currentUse
• bool isMailboxAvailable
• ?string organicUnit
• ?Capacity capacity
• ?PersonId responsible
• ?string shortComment

Core value objects:

• Address: {BUILDING}/{FLOOR}-{ROOM} format
• Experiment: constrained list (alice, atlas, lhcb, cms)
• CurrentUse: controlled code list with display names
• IntendedUse: controlled intended-use labels
• Height: meters and feet conversion helper
• SurfaceArea: square meters and square feet conversion helper
• FloorType: controlled floor-type labels
• Capacity: non-negative integer value
• LocationId, PersonId: typed integer identifiers

Repository contract:

• findLocationById(LocationId): ?Location
• findLocationByAddress(Address): ?Location
• findLocationsByExperiment(Experiment): Location[]
• findLocationsByCurrentUse(CurrentUse): Location[]
• searchLocationsByAddress(string): Location[]

Running Locally

# Install dependencies
composer install

# Run tests
composer run test:unit

# Static analysis
composer run test:types

# Coding standard
composer run test:lint

# Auto-fix coding standard
composer run fix:lint

Coverage (requires Xdebug coverage mode):

XDEBUG_MODE=coverage composer run test:ci

Contributing

1. Branch naming: feature/short-description or fix/short-description
2. Commit style: prefer the project convention with a gitmoji prefix
3. Quality gates: test:unit, test:types, and test:lint must pass before merge
4. Coverage: CI target is at least 95% line coverage

Project Links