Php Obj Laravel Package

Getting Started

This is a code-generation / scaffolding utility, not a runtime serializer. You feed it a class definition string (fields and types) and it emits a JS object literal, a YAML block, a PHP annotation, or a plain string. Think of it as a lightweight multi-target emitter for object shapes — handy for generating front-end contracts, Doctrine-style annotations, or config fixtures.

Audit before you install. With 0 stars and 0 dependents, verify the PHP version constraint and read the source in one sitting — the library is small enough.

composer require ntlab/php-obj

Then check composer.json for the PHP range and skim src/ for the actual API surface. The README and tests are your source of truth; the class names in the snippets below should be confirmed against the source, as the namespace/entry point may drift.

First real use case: pick a format you currently hand-write. A DTO or model that you keep re-expressing as a JS constant, a YAML config, or a docblock annotation. Emit it programmatically in an Artisan command and diff against what you already have committed:

use NTLab\Object\Obj; // verify actual FQCN

$obj = Obj::fromString('id:int, name:string, active:bool, createdAt:datetime');

echo $obj->toJS('User');        // JS class/object literal
echo $obj->toYAML();           // YAML mapping
echo $obj->toAnnotation();     // PHP docblock annotations
echo $obj->toString();         // plain string representation

Start with the JS emitter if you're a full-stack Laravel shop (front-end contract files), or the annotation/YAML emitter if you scaffold entities or config artifacts. Pick the single format that unblocks a specific task today; don't wire all four at once.

Implementation Patterns

Single source of truth for object shapes. Define your field list once (a plain string or your domain model), then emit to every target you need from that single definition. Treat the input as the contract and the four emitters as projections:

class ObjectShapeGenerator
{
    public function __construct(private string $shape) {}

    public function js(string $name): string { return Obj::fromString($this->shape)->toJS($name); }
    public function yaml(): string          { return Obj::fromString($this->shape)->toYAML(); }
    public function annotation(): string    { return Obj::fromString($this->shape)->toAnnotation(); }
}

Wrap it behind your own interface. Even a one-file wrapper buys you the ability to swap in Symfony Serializer, var_export, or a hand-rolled dumper without touching call sites. Do this on day one — not because you expect to swap, but because it stops the package leaking into controllers, models, and Blade views.

Artisan command as the entry point. The natural Laravel home is php artisan make:objects or a similar codegen command. It runs offline, produces diffable text, and can be validated in CI. Example shape:

class GenerateFrontendContract extends Command
{
    protected $signature = 'codegen:contract {shape} {--out=resources/js/contracts.js}';
    // read $this->argument('shape'), call the wrapper, write to file
}

Golden-file testing. Commit the expected output as fixtures and assert byte-for-byte in PHPUnit. This is your only real guardrail with an unmaintained dependency:

$this->assertSame(
    file_get_contents(base_path('tests/fixtures/user.js')),
    $generator->js('User'),
);

Fixture / config generation. A second good fit: generate seed YAML or fixture annotations from a DTO. Use it to keep hand-maintained fixtures honest — regenerate in a test and assert no drift.

One-way projection, not round-trip. Always emit out, never parse back in from generated YAML/JS/annotations. Round-trip is where escaping bugs and format drift bite hardest. If you need round-trip, use symfony/yaml and Symfony Serializer instead.

Gotchas and Tips

Escaping is the top risk. Multi-format emission implies escaping rules per target — JS string literals, YAML quoting, docblock syntax. Bugs produce silently malformed output that only fails downstream. In CI, round-trip the YAML through symfony/yaml::parse(), JSON.parse-style validate the JS (or embed in a Node check), and lint generated annotations. Do not ship a codegen path that only does string equality tests against your own emitter.

Never emit JS from untrusted input. If the shape string or field names derive from user-controlled data, this becomes an injection surface. Keep the input in source control (developer-authored shape strings, hard-coded DTO field lists), not from a request.

Inspect reflection / traversal behavior first. Confirm how it walks classes: public properties only, or getters via reflection? Does it handle typed properties, enums (PHP 8.1+), readonly properties, closures, and resources? Run a spike against a representative object — enums, DateTimeImmutable, nested collections — before you rely on any output. This is the single biggest unknown for a package with no community reports.

Depth-limit cycles in the wrapper. Cyclic object graphs will hang or throw. Wrap the call with your own depth guard or a pre-check that detects cycles before handing the object to the package. Never pass a raw Eloquent model with $model->relation->backReference into it.

Pin an exact version. No ^ range. With zero dependents, patch releases are effectively unreviewed. Commit composer.lock and mirror/fork the package if it becomes load-bearing so an upstream deletion or force-push can't break your build.

Include it in your Laravel/PHP upgrade matrix. "Silent break on Laravel 12" is a realistic failure mode. Add the wrapper to your dependency-upgrade checklist even though it's a minor tool dependency.

Namespace will drift — confirm before copying snippets. The public API is small (from-string constructor + per-format to* methods), but with no docs of record, use NTLab\Object\Obj; and method names may differ from the actual source. The tests in repo/tests/ are the ground truth.

Extension points are likely closed. Don't count on per-type custom handlers. If you need one, fork the small codebase or pre-process the shape before calling in. A 200-line dumper you own is a legitimate competitor to a 0-star dependency — the fallback is cheap.

Debug output use case. A legitimate low-risk use: dump($obj->toString()) for readable object snapshots during local development or test failure messages. Safe because it's loud if it breaks, contained to a dev path, and doesn't touch production serialization.

Name an owner. With one maintainer and no SLA, assign an internal owner of the wrapper and record a short ADR stating why the dependency exists and what triggers its removal. Otherwise it quietly becomes load-bearing and no one notices until a PHP upgrade.

Performance is unproven. Fine for offline codegen; don't benchmark it into the request path on the assumption that it's fast because it looks lightweight. Reflection-based traversal on large graphs can surprise you.

Where it does not belong: HTTP responses, queue payloads, API contracts, anything user-facing, untrusted input deserialization, or as the backbone of a data-portability strategy. If a feature graduates to customer-facing, re-run build-vs-buy against symfony/serializer.