Laravel Patrowl Laravel Package

Product Decisions This Supports

• Build vs. buy (integration layer): The decision to consume Patrowl through this package rather than hand-rolling an HTTP client is now much easier to justify. v2.0.0 ships typed DTOs across the EASM domain (domains, IPv4s, resolutions, ASNs, services, web servers, certificates, vendors, products, technologies, technology detections, CVEs). That is precisely the mapping/parsing work that normally tips a team toward "we'll just write our own client" — it's now done, documented in the README, and covered by examples.
• Roadmap: read-only external attack surface reporting. EASM is read-only in this release, which means exposure dashboards (certs, tech stack, CVE detections by asset) can be scoped as a reporting feature with no write-path risk and no dependency on platform-side changes. Low risk, demoable, and it doesn't block other work.
• Roadmap: control coverage views. controls()->assets($controlId) is the only way to get impacted/potentially-impacted assets, because the control detail endpoint returns empty assets_impacted and assets_warning. Any "which assets does this control affect?" screen depends on this method — treat it as a hard dependency when scoping that feature, not an implementation detail.
• Feature scope: tenant/org restructuring as a product capability. assets()->move($assetId, $targetOrganizationId, deleteSource: true) turns org consolidation (M&A, customer offboarding, re-org) into a workflow we can ship instead of a manual ops runbook. Product decision it forces: owners, teams, and groups are not copied and are returned in the result — so either we require re-assignment as an explicit step, or we surface a "needs owner" queue. Decide which before committing the feature.
• Data model: explicit default organization. Removal of organizations()->default() — combined with DTOs no longer reading Laravel's config() (which previously overrode the connector's default org) — means tenant resolution is now an explicit product decision per request context rather than an ambient fallback. Good for correctness, but it is a real behavior change to design around.
• Deprecation-driven scope cuts: assetTags()->all() and get() are removed because the API no longer serves those routes, and assets()->replace() is gone. Any tag-catalog UI or upsert-style idempotent sync design is invalidated. Tag management becomes attach/detach-only; sync jobs need a read-modify-write path. Scope these as follow-on work, not silent regressions.
• Delivery sequencing: v2.0.0 is a breaking upgrade. It should be its own work item with a compatibility pass (grep for removed methods, review UPGRADE.md), not folded into a feature sprint on the assumption of drop-in replacement.

When to Consider This Package

Adopt when:

• You're on Laravel/PHP and already committed to (or evaluating) Patrowl as the security/EASM platform.
• Your need is read-heavy: EASM inventory, exposure reporting, control-impact analysis.
• You want typed DTOs and auto-pagination instead of array-wrangling and manual paging loops.
• You need multi-org asset operations, including cross-organization moves.
• You're starting fresh — a new integration inherits all of v2.0.0's fixes with none of the migration cost.

Look elsewhere or defer when:

• You have in-flight features depending on removed surface area: organizations()->default(), assets()->replace(), assetTags()->all()/get(), or organizations()->all() returning something other than OrganizationLiteData[]. If you can't absorb that migration this quarter, pin and defer.
• You need to write EASM data. This release is explicitly read-only.
• You need asset tag enumeration from the API. That's an upstream API removal — no SDK version restores it, so don't evaluate packages hoping to solve it.
• You need owner/team/group preservation across org moves. move() deliberately doesn't copy them; if that's a hard requirement, this isn't the tool.
• You'd be relying on Laravel's config() for connector behavior. DTOs no longer read it by design (it crashed outside Laravel and overrode the connector's default organization) — verify your configuration path before upgrading.

Also worth a review gate: assets()->create() now throws AssetAlreadyExistsException on HTTP 208. If your sync logic previously treated "already exists" as success, that is a silent behavior change in an error path — test it before rollout. Conversely, assets()->delete(), addTag(), removeTag() now hit current endpoints (the old routes return 403/404), so previously broken write paths may actually start working; re-test rather than assuming prior behavior.

How to Pitch It (Stakeholders)

For executives: The Patrowl integration now exposes read-only EASM data — external attack surface visibility covering certificates, technologies, services, and CVE detections per asset. We can ship this as a reporting capability without building a scanner or maintaining a bespoke API client. The v2.0.0 upgrade is a bounded, documented engineering task with a published upgrade path, not a rewrite; cost concentrates in a handful of removed convenience methods. Net: a new customer-facing security surface at integration cost, not platform cost.

For engineering: v2.0.0 adds typed DTOs for the full EASM read surface with README documentation, auto-pagination on the control→asset lookup (controls()->assets()), and a first-class cross-org asset move that reports back the fields it does not copy. DTOs are decoupled from Laravel's config(), so the same code runs in queue workers and CLI. Breaking changes are enumerated in UPGRADE.md; the ones that matter are the removal of assetTags()->all()/get(), assets()->replace(), and organizations()->default(), the changed return type of organizations()->all(), the new AssetAlreadyExistsException on HTTP 208, AssetInListData::$relatedTechnologies becoming an array, and CreateAssetGroupData::$criticality becoming non-nullable. Several write paths were also fixed against current endpoints (delete, addTag, removeTag, bulk update with trailing slash), so retest them rather than trusting existing test assumptions.

Risk posture: pin the version, run a targeted search for the removed methods, review the 208 "already exists" path, and schedule the upgrade as discrete work with a compatibility pass.