Form Spatial Laravel Package

Getting Started

Reality check before you install: this bundle targets Symfony 2.x (the AppKernel / app/config/config.yml era), has had no release since April 2018, and is archived upstream. It is GPL-2.0, has zero dependents and a single-digit star count, so treat it as reference source you may vendor/fork rather than a dependency you composer require into a live product.

Minimal path in a Symfony 2.x app:

composer require looptribe/form-spatial

// app/AppKernel.php
public function registerBundles()
{
    $bundles = [
        // ...
        new Looptribe\...\...Bundle(), // FQCN exactly as printed in the README
    ];
}

There is normally no service configuration to write — the value of the bundle is a form type plus (usually) a Twig form-theme block and a data transformer. If the bundle ships a DependencyInjection/ extension, check whether it exposes anything worth configuring (SRID, default widget, precision) before assuming it is plug-and-play.

Where to look first, in this order:

1. README.md — the field type alias and the expected value type (WKT string vs. a geometry object) are the two facts everything else depends on.
2. Form/Type/*.php — buildForm(), getParent(), getBlockPrefix()/getName(), and which data transformer it attaches. This tells you the actual contract in under five minutes, and it is more reliable than the README.
3. Resources/views/Form/*.html.twig — whether the widget is a plain <input>/<textarea> or a JS map.
4. composer.json — PHP constraint, Symfony component constraints, and which geometry library (looptribe/geo or similar) it expects.

First use case: adding a "location" field to an entity form and persisting it.

// src/AppBundle/Form/PlaceType.php
$builder
    ->add('name')
    ->add('location', SpatialType::class, [   // alias from the README, e.g. 'spatial'
        'required' => false,
        'label'    => 'Coordinates',
    ]);

Wire the entity column as string/text (WKT or GeoJSON) for a first proof of concept. Do not start by wiring a Doctrine spatial column — that drags in a second, equally stale dependency and doubles the failure surface.

Implementation Patterns

String-in, string-out (the low-risk pattern). Use the type as a validated text field: the user pastes or enters WKT/GeoJSON, the form maps it to a string property, and you normalise on persist. This works even if the JS widget is broken and gives you a clean upgrade path later.

Data transformer for a domain object. The moment you want $place->getLocation() to return a Point rather than a string, add your own transformer instead of relying on whatever the bundle ships:

$builder->add('location', SpatialType::class)
        ->addModelTransformer(new PointToStringTransformer($reader, $writer));

Keep the transformer dumb — parse to/from one canonical format (WKT is the safest bet; it is unambiguous about SRID and has mature parsers). Reverse-transform failures into TransformationFailedException, not \Exception, so the form shows a field error instead of a 500.

Compound field with a map widget. The usual architecture is: hidden/text input holds the serialised geometry, a JS map (Leaflet/Google) writes into it on change, and the bundle's form theme renders the container. If the bundle does not ship the JS, add it in your own Resources/views/Form/fields.html.twig override rather than editing vendor/ — you will need that override anyway to survive an update or a fork.

Validation belongs to you. Add a @Assert\Callback or a custom constraint on the entity that parses the value and rejects bad geometry. Form types validate shape, not semantics; an "empty polygon with three points" will happily pass a NotBlank.

Symfony form tests as your safety net. Because there is no upstream CI, write a TypeTestCase that submits a known WKT string and asserts the model value. That test is what tells you when a PHP or Symfony upgrade breaks the bundle:

$form = $this->factory->create(SpatialType::class);
$form->submit('POINT(2.35 48.85)');
$this->assertTrue($form->isSynchronized());

Reuse across forms, not inheritance. The bundle is small; if you need behaviour it lacks (SRID selection, multiple geometries), compose a new type with getParent() returning the bundle's type. Do not subclass — these bundles change buildForm() signatures between patch releases.

Gotchas and Tips

• Symfony 2 is EOL. Symfony 2.8 lost security support in 2018, the same year as this release. Everything below is secondary to that. In Symfony 5/6/7 this bundle will not install cleanly (component constraints, getName() vs. getBlockPrefix(), AppKernel removal, no autowiring-friendly service definitions). Budget for a fork, not a composer require.
• GPL-2.0 is a genuine constraint, not a formality. Unlike MIT/Apache packages, linking this into a closed-source SaaS or distributed product is a licensing decision, not a technical one. Many teams will reject it outright; get that cleared before writing code against it.
• Coordinate order is the classic bug. WKT and GeoJSON disagree (POINT(lng lat) vs [lng, lat]), and so do Google Maps and Leaflet. Pick one order, document it at the transformer, and unit-test a known landmark (e.g. the Eiffel Tower) so swaps fail loudly.
• SRID is implicit and silent. Most of these bundles assume 4326 and never surface it. Anything consuming the data — PostGIS ST_GeomFromText(..., 4326), a tiling service — will quietly misbehave if the assumption drifts.
• Float precision. Round-tripping through float casts can move a coordinate by a metre. Keep the persisted representation as the original string until you have a reason not to.
• Parsers throw, forms should not. Wrap geometry parsing in try/catch and convert to TransformationFailedException. Raw InvalidArgumentException from a WKT parser during submit() produces a 500 on user input.
• Debugging the "type not found" error. If the bundle is registered but the alias is unknown: php app/console debug:container --tag=form.type (Symfony 2.8+) and check the bundle's Resources/config/ XML/YAML — a missing service definition is the usual cause, often because the bundle class name in AppKernel is wrong.
• The profiler is your friend. The Form panel shows submitted vs. model data; if the model value is null after a valid submit, the data transformer is the culprit, not the widget.
• Extension points worth reusing even if you drop the bundle: the form type (as a template for your own), the data transformer (portable), and the Twig theme block (copy into your app's theme). The DI wiring is the part you least want to inherit.
• Not portable to Laravel. This depends on the Symfony Form component and its renderer; there is no Laravel adapter and no realistic path to one. In a Laravel codebase the only salvageable pieces are the geometry value objects/transformer logic — reimplement the field as a Blade partial + a Rule object, and take the WKT parsing library rather than the bundle.
• If you do adopt it, vendor it. Fork to your own namespace, pin the commit, add the missing CI (form tests against your target PHP), and treat it as internal code. With 7 stars and no maintainer, "upstream will fix it" is not a plan.