Macdom Bundle Laravel Package

Getting Started

The v1.0.0 release is the package's first public tag, so treat the README as the primary spec and the release notes as a compatibility statement rather than documentation. Three facts are actually load-bearing here: PHP >= 7.0, a hard dependency on Macdom ^ 3.0, and "initial release" — meaning there is no upgrade path to reason about, but also no track record to lean on.

Minimal steps:

1. composer require <vendor>/<package>:^1.0 — pin the major explicitly. At v1.0.0 a ^1.0 constraint is safe; a bare dev-main is not, since there are no tagged predecessors to diff against.
2. Verify the dependency resolves before writing any code: composer why macdom/macdom and composer show macdom/macdom. ^3.0 means >=3.0.0 <4.0.0, so if another package in your tree already pulls Macdom 2.x or 4.x you have a hard conflict and no room to negotiate.
3. Check the PHP floor against your own. >= 7.0 is the package's minimum, not a recommendation — it tells you the code was likely written against 7.0–7.4 idioms and may emit deprecations on 8.x. Run php -v and, if you're on 8.1+, do a quick php -d error_reporting=E_ALL smoke test before adopting.
4. Look at these files first, in order: composer.json (autoload map, service provider, facade alias), src/ (the public surface is usually 2–5 classes), config/ if present, and tests/.
5. If a config file ships, publish it: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". On Laravel 5.5+ the provider is auto-discovered; on older skeletons register it manually in config/app.php along with any facade alias.
6. First use case: the classic DOM-wrapper flow — take an HTML or XML string, load it, query or mutate nodes, serialize it back. Build the smallest possible version of that (load a fixture, select one node, echo the result) before integrating it into a real feature.

Implementation Patterns

Keep the package behind your own boundary. A DOM wrapper at v1.0.0 with a caret-pinned transitive dependency is exactly the kind of thing you want to be able to swap. Define a small interface in your app (HtmlTransformer, DocumentParser, whatever fits) and implement it with the package's classes in one adapter class. Everything else depends on the interface. If Macdom 4 lands with breaking changes, or the package stalls, you rewrite one file.

Register it in the container, not with new. Bind the package's entry point as a singleton if it is stateless or holds a configured parser instance; bind it as a fresh instance if it accumulates document state. Resolve through the container in jobs and commands so tests can swap a fake.

Parse in a job, not in a request. DOM operations on large documents are memory- and CPU-bound. If you are importing, scraping, or transforming markup at any volume, push the work to a queued job with an explicit $timeout and $tries, and make the job idempotent by keying on the source identifier.

Treat serialized output as the contract. Assert on the resulting string (normalised whitespace) rather than on node object internals. That keeps your tests valid across Macdom 3.x patch releases and across any future swap of the underlying library.

Fixture-driven tests. Commit small .html and .xml fixtures under tests/Fixtures/. Cover the ugly cases from day one: entities, CDATA, self-closing tags, and malformed markup. These are where DOM libraries diverge, and they are the regressions you will actually hit.

Cache parsed results where the input is stable. If the same document is transformed repeatedly, cache the output keyed by a hash of the input plus the package version. Invalidate on deploy.

Compose with Laravel's pipeline, not around it. If the transformation is one step among several (fetch → parse → sanitise → persist), express it as a pipeline stage or a dedicated action class rather than a fat controller method.

Gotchas and Tips

• The >= 7.0 floor is a signal, not a feature. Expect pre-8.0 idioms: no typed properties, no union types, possibly no declare(strict_types=1). On PHP 8.1+ watch for null passed to non-nullable internal parameters and dynamic-property deprecations. Run your test suite with E_ALL and treat deprecation output as a to-do.
• Macdom ^3.0 is a brittle seam. Caret constraints on a 3.x dependency mean any 4.0 release is a hard blocker for this package until it ships a new major. Check Macdom's release cadence and whether it is actively maintained; an unmaintained transitive dependency is the most common way a package like this becomes a liability.
• v1.0.0 means the API is a guess until you read the source. Release notes list requirements, not behaviour. There is no changelog history to tell you what was considered and rejected. Read src/ before designing around it — it is probably a few hundred lines.
• Libxml error handling swallows problems. DOM libraries typically call libxml_use_internal_errors(true) and discard the buffer. If malformed input silently produces a partial tree, you will not know. Wrap the parse call, capture libxml_get_errors(), and surface or log them — then clear the buffer, since libxml state is global and leaks between parses.
• Encoding bites before anything else. DOM loaders assume UTF-8 unless the document declares otherwise. Convert input with mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8') or a proper <?xml encoding="utf-8"?> prefix, and strip a BOM if your source is user-supplied or read from a file.
• Debug by dumping serialized output, not objects. var_dump on a node reference is a recursive wall of text. echo $doc->saveHTML() (or the package's equivalent accessor) tells you what actually happened.
• Watch memory on large documents. DOM is a full in-memory tree. If you are parsing multi-megabyte HTML, raise memory_limit in the job and unset document references explicitly when done — PHP's GC will not necessarily reclaim a large cyclic tree promptly.
• Extension points to look for: container bindings (rebindable, so you can override the parser), a config file (options passed to Macdom), and macros if a facade is registered. Macros are the cheapest hook if you need to add behaviour without forking — but they are global, so they leak between tests. Register them in a service provider and reset them in tearDown.
• Pin exactly in CI, loosely in the app. Use composer update --prefer-lowest in CI to prove the package works at the bottom of its ^3.0 Macdom range, and commit composer.lock for the app. A green build against only the latest Macdom patch tells you very little.
• Revisit this assessment at the first 1.x minor. At v1.0.0 there is nothing to judge about stability or maintenance velocity. What you learn from the next two releases — and whether Macdom majors get tracked — should determine whether the adapter boundary stays a formality or becomes a migration plan.