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

Layer	Tool	Version
Language	PHP	^8.2
Data access	Doctrine DBAL	^4.2
Unit tests	PHPUnit	^10
Static analysis	Psalm	^5
Coding standard	PHP_CodeSniffer	^3.6 (PSR-12)
CI/CD	GitLab CI	-
Package registry	Packagist	-

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

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

Project Links

Resource	URL
GitLab repository	https://gitlab.cern.ch/fence/common/locations-service
Packagist package	https://packagist.org/packages/glance-project/locations-service
CERN GitLab	https://gitlab.cern.ch

glance-project / locations-service

Maintainers

Package info

Statistics

Security