Sde Laravel Package

Getting Started

• Install with composer require nicolaskion/sde, then publish the package assets: config (config/sde.php), migrations, and any console commands the service provider registers. Run php artisan migrate before anything else — the models assume the shipped schema, including the newly added 2D position columns on solarsystems.
• Look first at config/sde.php (source URL, storage path, connection/chunk settings) and then the DTO classes under the package's Data/Dto namespace. As of v0.6.1 there is a DTO for essentially every core entity (types, dogma effects, effect modifiers, solar systems), so the DTOs are the fastest way to learn the shape of the data without opening the raw YAML/JSON.
• Your first use case should be a single import plus a lookup: run the SDE download/seed command (php artisan sde:..., check php artisan list for the exact signature), then SolarSystem::where('name', 'Jita')->first(). From there you can immediately read both the legacy 3D position vector and the new 2D position fields.
• Budget time for the first run. The initial SDE download and full seed is slow and heavy; the v0.6.1 timeout bump and the seeding-command resource improvements exist precisely because of this. Run it once locally, keep the resulting database dump, and reuse it rather than re-seeding per developer.

Implementation Patterns

• Treat the package as a data layer, not a domain layer. Keep your own Eloquent models/aggregates on top and reference package models by ID (type ID, system ID, effect ID). That way a package update that changes a column or DTO property only breaks your adapter, not your whole app.
• Use DTOs for import/processing pipelines, Eloquent for queries. The dogma/effect DTOs are ideal for the read-heavy transformation step (walking effect modifiers, computing derived stats), while the models stay the query surface. EffectDto and EffectModifierDto now carry nullable fields, so a "normalise to your own value object" step is worth the twenty lines.
• Two-coordinate pattern for routing and maps. The new 2D position fields are a separate representation from the classic 3D vector. For jump-range checks, distance plots, or map rendering, read the 2D fields directly instead of projecting 3D→2D yourself; for anything Eve-accurate (gate ranges in 3D, bookmarks), use the original vector fields. Keep a small helper on your side, e.g. distance2d(SolarSystem $a, SolarSystem $b), so switching representations later is one edit.
• Isolate the seed as an artisan/CI job, not a request path. Wire the download+seed command into a scheduled job or a deploy step against a dedicated connection, and never call it from a controller. Configuring a separate sde database connection is the cleanest way to keep a ~million-row import from competing with app tables.
• Version-pin and cache. Because the underlying SDE is a periodically-republished dataset (and the Jove system list has needed corrections more than once), treat an import as an artifact: pin the package version in composer.json, snapshot the seeded DB, and rebuild rather than incrementally patching rows.
• Progressive integration. Start with solarsystems + types (the 90% use case), then layer on dogma/effects and flags only when you need them. The DTO/seed command surface is broad enough that importing everything "because it's there" is a real cost in disk and seed time.

Gotchas and Tips

• Nullable DTO fields are load-bearing. v0.6.1 explicitly made EffectDto/EffectModifierDto fields nullable. If you wrote non-null assumptions against 0.6.0, those will now fail more quietly (or loudly) — audit any ->modifier->value style chains and use null-safe access.
• Strict types in data files. jove_observatories.php now declares strict_types=1. If you extend or override that data file, integer strings (e.g. "30000142") will throw under strict comparison instead of coercing. Same applies to any DTO constructor you call by hand.
• Jove data has history. Two separate fixes in this release (correct jove systems, remove false systems from jove list) mean any cached copy of the Jove region is suspect. If you already seeded, re-run the import or at least re-seed that dataset — do not trust a pre-0.6.1 snapshot.
• Long-running download. The download request timeout was raised but is still finite. On slow links or corporate proxies, prefer downloading the archive manually into the configured storage path and having the command consume the local file; wrap the command in a job with its own timeout and retry policy.
• Resource usage is better, not free. The seeding command rework reduces memory, but a full seed is still an I/O and transaction-heavy operation. Wrap it in --no-interaction, disable query logging, and consider chunk-size tuning via config if you hit memory ceilings.
• Debugging a missing row is almost always an import-scope issue rather than a model issue: check whether the relevant sub-command ran, whether the connection in config matches the one your models use, and whether the dataset you downloaded is the expected build. The PHPStan level-max pass in this release means type errors are more likely to surface as DTO/constructor complaints than silent nulls — a good first place to look if an import path breaks after upgrading.
• Extension points to prefer: config overrides for paths/connection/chunking, your own wrapper commands that call the package commands, and adapters around the DTOs. Avoid editing published migrations or package data files directly; those are exactly what the 0.6.x patch releases keep touching.