[3.x] Proposal to remove the `MediaFile::EXTENSIONS` constant

[emmadesilva]

HydePHP media copying in v3 (Deep Research)

Abstract

HydePHP has historically used a configurable list of file extensions to determine which files are copied from the _media directory to _site/media.

For HydePHP v3, I want to reconsider whether that allow-list still provides enough value to justify its complexity. Since _media is already a directory specifically intended for public assets, should Hyde simply copy everything placed there?

A possible middle ground would be to copy all files while excluding a small set of known junk or placeholder files, such as .gitkeep, .DS_Store, Thumbs.db, and AppleDouble ._* files.

This document evaluates the costs and benefits of each approach and recommends the behavior that makes the most sense for HydePHP v3.

Background

In HydePHP v2 and earlier, Hyde used MediaFile::EXTENSIONS to determine which files in _media qualified as media files and should be copied into _site/media.

The default extension list contained:

png, svg, jpg, jpeg, webp, gif, ico, css, js

Users could extend or replace this list through the hyde.media_extensions configuration option.

This provided a clear definition of what Hyde considered a media file, but it also meant that files outside the configured list were silently excluded from the generated site. Legitimate static assets such as PDFs, fonts, JSON files, web manifests, source maps, and downloadable archives therefore required additional configuration.

HydePHP v3 is currently being developed on the master branch. This gives us an opportunity to reconsider the old behavior without introducing a breaking change into an existing stable release.

Recommendation

For HydePHP v3, _media should become a true passthrough directory:

1. Recursively copy all files from _media to _site/media.

2. Exclude a small set of known junk and placeholder files.

3. Allow users to configure additional exclusion patterns.

4. Stop using MediaFile::EXTENSIONS as the primary rule for deciding which files are copied.

The directory itself should define publication intent:

Everything placed in _media is public unless it is explicitly excluded.

There was value in the extension constant, particularly as a guardrail against accidentally publishing unrelated files. However, that value was limited in a directory already dedicated to publishable assets. The allow-list also introduced recurring costs through unexpected behavior, documentation requirements, configuration discovery, and maintenance whenever new asset types became common.

Existing user expectations

Hyde’s documentation has consistently described _media as the location for static assets that are copied into the generated site.

This creates a straightforward user expectation:

Put a file in _media, and Hyde will publish it under _site/media.

An extension allow-list weakens that contract. A user can place a valid asset in the correct directory and still find that it was not copied because Hyde did not recognize its extension.

That behavior is especially surprising for common static assets such as:

• PDF documents

• Font files such as .woff, .woff2, and .ttf

• Web manifests

• JSON data files

• Source maps

• Text files

• Downloadable archives

The user should not need to discover an advanced configuration option before Hyde will copy an otherwise ordinary static file.

Comparable public-directory models

The closest comparison to Hyde’s _media directory is the public or static directory used by other static-site generators.

Tools such as Astro and Hugo treat these directories as passthrough locations. Files placed there are copied into the generated site without being restricted to a predefined set of extensions.

This works because the directory name already communicates the contract: its contents are intended for publication.

Jekyll takes a more exclusion-oriented approach because it processes a broader source tree containing both public files and internal project files. It therefore needs additional include and exclude rules.

Hyde’s _media directory is already isolated from the rest of the project. It does not need the same defensive filtering as a generator that scans a mixed source directory.

Eleventy requires users to configure passthrough copy rules explicitly. Hyde already provides _media as a built-in convention, so requiring additional declarations would add configuration without improving the common case.

For Hyde, the Astro and Hugo model is the most relevant: a dedicated public directory should copy arbitrary files by default.

Cost-benefit analysis

Option 1: Keep the extension allow-list

Under this option, Hyde would continue copying only files whose extensions appear in MediaFile::EXTENSIONS or hyde.media_extensions.

Benefits

• Prevents many unrelated files from being published accidentally.

• Automatically filters common operating-system metadata and placeholder files.

• Provides a narrow and explicit definition of what Hyde considers media.

• Preserves existing behavior and configuration semantics.

Costs

• Legitimate static assets are silently ignored unless their extensions are configured.

• Users must learn about an advanced option to publish ordinary files.

• The default list requires maintenance as frontend asset types evolve.

• Documentation must explain that _media does not necessarily copy everything.

• The behavior conflicts with the natural interpretation of a dedicated public-assets directory.

• Extension-based file discovery adds implementation complexity.

• A file’s extension is not always a reliable indicator of whether it should be public.

The allow-list provides protection, but it optimizes for accidental misuse of _media rather than its intended use.

Option 2: Copy everything

Under this option, Hyde would recursively copy every file from _media into _site/media.

Benefits

• Provides the simplest possible mental model.

• Supports all current and future asset types automatically.

• Matches the documented purpose of _media.

• Removes the need to maintain a media-extension registry.

• Eliminates configuration for common files such as PDFs and fonts.

• Produces behavior consistent with other dedicated public-directory systems.

• Makes the implementation easier to understand and test.

Costs

• Placeholder files such as .gitkeep may be published.

• Operating-system metadata such as .DS_Store and Thumbs.db may be published.

• Users who treat _media as general storage may unintentionally expose files.

• Version-control metadata could be copied if it somehow exists inside _media.

This option has the strongest developer experience, but publishing obvious junk files would make the generated output unnecessarily messy.

Option 3: Copy everything with explicit exclusions

Under this option, Hyde would recursively copy all files except those matching a small exclusion list.

Benefits

• Preserves the simple passthrough-directory model.

• Supports arbitrary asset types without additional configuration.

• Prevents common junk and placeholder files from being published.

• Allows advanced users to exclude project-specific files or directories.

• Avoids maintaining an ever-growing registry of valid extensions.

• Makes publication rules explicit and easy to explain.

• Better aligns the implementation with the purpose of _media.

Costs

• Requires a small amount of exclusion-matching logic.

• The default exclusion list must be maintained.

• An obscure junk file not included in the defaults could still be copied.

• Changes to the existing configuration model require migration documentation.

This option provides most of the simplicity of copying everything while preserving the useful protection offered by the old allow-list.

Comparison

Option | Developer experience | Legitimate asset support | Junk-file protection | Maintenance burden | Ecosystem fit -- | -- | -- | -- | -- | -- Keep the extension allow-list | Low | Medium | High | High | Low Copy everything | High | High | Low | Low | High Copy everything with exclusions | High | High | High enough | Low to medium | High

Copying everything with a small explicit exclusion list provides the best overall balance.

Proposed v3 behavior

HydePHP v3 should:

1. Treat _media as a recursive passthrough directory.

2. Copy all files regardless of extension.

3. Skip a small default set of known junk files.

4. Introduce a configurable exclusion list, such as hyde.media_exclude.

5. Deprecate or remove hyde.media_extensions as a file-discovery mechanism.

A possible default configuration could look like this:

'media_exclude' => [
    '.gitkeep',
    '.DS_Store',
    'Thumbs.db',
    '._*',
    '.git/**',
    '.hg/**',
    '.svn/**',
],

The exact pattern syntax would need to be defined, but it should support both filenames and recursive paths.

Default exclusions

The default list should remain intentionally small.

Good candidates include:

.gitkeep
.DS_Store
Thumbs.db
._*
.git/
.hg/
.svn/

These files have little or no legitimate purpose in generated website output.

Hyde should not exclude every dotfile by default. Unlike a general project source directory, _media is specifically intended for publication. Some hidden files may be intentionally public, and excluding all of them would recreate the same surprise caused by the extension allow-list.

The rule should therefore be:

Exclude known junk, not broad categories of potentially valid files.

Why .gitignore should not control publication

Hyde could technically reuse .gitignore rules when deciding which media files to copy, but this should not be the default.

.gitignore describes source-control policy. It does not necessarily describe publication policy.

A file may be excluded from Git because it is generated locally while still needing to be published. Conversely, a file may be tracked in Git but intentionally excluded from the generated site.

Using a dedicated media_exclude setting keeps these concerns separate and makes Hyde’s behavior easier to understand.

Support for .gitignore-aware exclusions could be introduced later as an explicit opt-in feature, but it should not define the default behavior.

Validation behavior

Changing _media to a passthrough directory does not require weakening Hyde’s asset validation.

Hyde can continue validating explicitly referenced assets and throwing a helpful FileNotFoundException when a referenced file does not exist.

These are separate concerns:

• Passthrough copying determines which files are eligible to be published.

• Asset validation determines whether an explicitly referenced file exists.

Allowing arbitrary file types in _media only broadens publication support. It does not prevent Hyde from reporting missing assets clearly.

Implementation outline

The implementation can remain simple:

1. Recursively enumerate files under the configured media directory.

2. Normalize each path relative to the _media root.

3. Test the relative path against the default and configured exclusions.

4. Create the corresponding parent directory under _site/media.

5. Copy each remaining file.

Laravel’s filesystem utilities or Symfony Finder can both support this model cleanly.

The implementation should avoid extension-based glob patterns. Direct recursive enumeration followed by explicit filtering is easier to understand, more portable, and easier to test.

Suggested tests

The v3 test suite should verify that:

• Existing image, CSS, and JavaScript files continue to copy.

• Files outside the old allow-list are copied.

• Nested files preserve their directory structure.

• Default junk files are skipped.

• Custom exclusion rules work recursively.

• Legitimate dotfiles can still be published.

• Empty directories do not need to be reproduced unless explicitly required.

• Explicitly referenced missing assets continue to produce helpful errors.

Example files should include:

docs/manual.pdf
fonts/app.woff2
data/site.json
manifest.webmanifest
downloads/example.zip
nested/assets/example.txt

Default exclusion tests should include:

.gitkeep
.DS_Store
Thumbs.db
._logo.png
.git/config
.hg/store/example
.svn/entries

Migration strategy

The cleanest v3 migration would be to replace extension-based discovery entirely.

Documentation should describe _media in plain language:

All files in _media are copied to _site/media, except files matching the configured exclusion rules.

Any documentation presenting media_extensions as the normal way to enable additional static files should be removed or updated.

There are two possible compatibility approaches.

Clean break

Remove hyde.media_extensions from copy discovery in v3.

This is the clearest option and is appropriate for a major release. Existing projects would generally gain support for more files rather than lose functionality.

The main observable difference would be that previously ignored files might now be copied unless explicitly excluded.

Transitional deprecation

Continue reading hyde.media_extensions temporarily while emitting a deprecation notice explaining that _media now uses passthrough semantics.

This provides a softer migration path, but it may also make the behavior harder to explain. It would need to be clear whether the extension setting still filters files, is ignored, or is translated into another rule.

Unless there is a significant compatibility concern, the clean break is preferable.

Conclusion

MediaFile::EXTENSIONS provided a useful guardrail in earlier versions of HydePHP, but it is not the best default publication model for v3.

Because _media is already a dedicated public-assets directory, the most intuitive rule is that files placed there should be published. Restricting publication by extension creates more friction and maintenance than value.

HydePHP v3 should therefore copy all files from _media recursively while excluding a small, explicit set of known junk and placeholder files. Additional exclusions should be configurable through a dedicated setting.

This gives Hyde a simple and durable contract:

Everything in _media is public unless explicitly excluded.

[emmadesilva]

Had a coding agent ground in the codebase:

Verdict

The direction is right: _media should behave as a passthrough directory in HydePHP v3. It better matches Hyde’s documentation, conventions, and “common things should work without configuration” philosophy.

However, the proposal underestimates the implementation and migration costs. In particular:

• MediaFile should absolutely remain.
• The current allow-list is not materially complex in code.
• Exclusions affect discovery, public APIs, Markdown rewriting, the dashboard, validation, and the realtime compiler—not merely file copying.
• Large arbitrary assets expose performance problems in the existing copying and cache-busting pipeline.
• The stated validation behavior is not currently safe for excluded files.

I would approve the product direction, but revise the implementation plan before coding it.

MediaFile should not be removed

Only MediaFile::EXTENSIONS is tied to extension discovery. MediaFile itself is Hyde’s public static-asset value object. It provides:

• Source and output path normalization
• Existence validation
• Relative and absolute URLs
• Cache-busting hashes
• File sizes and MIME types
• Hyde::asset(), Hyde::assets(), MediaFile::all(), and MediaFile::files()

Those responsibilities are visible in MediaFile.php. PDFs, fonts, JSON, and archives can already be represented by MediaFile; they are simply not auto-discovered.

The correct change is therefore:

Remove extension filtering from media discovery, not the MediaFile abstraction.

Renaming it to AssetFile would create broad API and documentation churn without solving anything. CSS and JavaScript already demonstrate that “media” is being used in Hyde’s broader static-asset sense.

I would retain MediaFile::EXTENSIONS as a deprecated, unused compatibility constant for v3. Existing published configuration directly references it in config/hyde.php. Removing the constant makes an unmodified upgrading application fail while loading configuration. Keeping it costs virtually nothing and allows removal in v4.

What the actual pipeline looks like

Media discovery is shared infrastructure, not just a copying detail:

FileFinder + media_extensions
              │
              ▼
       cached Hyde::assets()
        ├── build-time copying
        ├── Hyde::asset() / MediaFile API
        ├── Markdown image rewriting
        └── realtime dashboard media library

Realtime asset serving ──────► reads _media directly, bypassing discovery

The allow-list itself is only this call in HasMediaFiles.php:

Filesystem::findFiles(
    Hyde::getMediaDirectory(),
    Config::getArray('hyde.media_extensions', MediaFile::EXTENSIONS),
    recursive: true
);

Consequently, “extension-based discovery adds implementation complexity” is overstated. The current mechanism is one configuration lookup passed to an existing generic finder. Copy-everything without exclusions would indeed be simpler; copy-everything with configurable glob exclusions is more code than the current allow-list.

The real benefit is reduced user-facing complexity and surprise, not a dramatic reduction in framework code.

Important side effects missing from the proposal

1. Most proposed defaults are already excluded

Hyde’s FileFinder uses Symfony Finder in FileFinder.php. Symfony Finder ignores dotfiles and VCS directories by default:

• .gitkeep
• .DS_Store
• ._*
• .git/
• .hg/
• .svn/

They are already invisible even if Hyde stops filtering by extension. Thumbs.db is the only proposed default that would newly require explicit filtering.

This creates an important choice:

• Calling findFiles(..., false, true) copies all non-hidden, non-VCS files.
• Supporting “legitimate dotfiles can still be published” requires explicitly enabling dotfile discovery and then adding selective exclusions.

So the proposal’s default exclusion system is not just additive filtering—it changes Symfony’s hidden-file behavior too. Files such as .env, .vite/manifest.json, and arbitrary hidden directories could become public unless considered carefully.

VCS patterns do not need to be reimplemented; Symfony already excludes those directories independently.

2. Excluded assets currently validate but produce broken links

MediaFile::get() first looks in discovered assets, but falls back to constructing a MediaFile for any existing source file:

return Hyde::assets()->get($path) ?? static::make($path);

See MediaFile.php.

Therefore, with the proposed exclusions:

Hyde::asset('private/report.pdf')

could pass existence validation and generate a /media/private/report.pdf URL even though the file was excluded from the build.

The document’s claim that validation can remain unchanged is thus incomplete. Missing-file validation remains intact, but publication validation does not.

The asset helper should reject explicitly referenced excluded assets with an actionable error, or the design must explicitly state that references override exclusions. Silently generating a broken link is not Hyde-like.

3. Arbitrary large files expose inefficient copying

The transfer task does not use a streaming filesystem copy. It loads each complete file into PHP memory and writes it back:

Filesystem::putContents($sitePath, $file->getContents());

See TransferMediaAssets.php.

That is tolerable for CSS and normal images, but the proposal explicitly adds archives, PDFs, fonts, and potentially videos. A large downloadable archive could cause a significant memory spike.

This work should include switching to Filesystem::copy($source, $target) and checking its result.

4. Every discovered file can be hashed during Markdown processing

The Markdown link processor iterates over every discovered media file in DynamicMarkdownLinkProcessor.php. Its replacement construction calls getLink(), which computes a cache-busting hash.

Broad discovery can therefore cause every PDF or archive to be hashed even when the file is never referenced by an <img> element. Combined with copying, some large assets may be read twice during a build.

The processor should only resolve and hash an asset after confirming that the relevant source path occurs in the HTML. Ideally, it should also stop treating arbitrary downloads as candidate Markdown images.

5. Development and production policies can diverge

The realtime compiler serves files by directly checking _media, bypassing MediaFile::all() and all discovery rules:

$file = BASE_PATH.'/_media/'.str_replace('media/', '', $path);

return file_exists($file) ? $file : null;

See AssetFileLocator.php.

This has two consequences:

• Today, a JSON or PDF can work under hyde serve but disappear from a production build. Passthrough fixes that existing inconsistency.
• With media_exclude, an excluded file would still be served during development unless the realtime compiler adopts the same policy.

A single publication-policy implementation needs to govern discovery, build copying, explicit asset references, and development serving. Custom configuration may require booting Hyde for media requests, which changes the realtime compiler’s current boot-free /media/ fast path.

6. The dashboard becomes a general static-file library

The dashboard consumes MediaFile::all(). It has a generic BINARY placeholder for unknown extensions, so it will not fundamentally break. However, its UI still uses image-oriented labels, and its editor action explicitly rejects anything outside the old extension family in DashboardController.php.

After this change, PDFs, fonts, archives, maps, and JSON files will appear in the “Media library,” usually with a BINARY card and a disabled/rejected edit action. That deserves a small dashboard UX pass, even if only to rename tooltips from “image” to “asset” and improve common placeholders.

7. Symlink behavior should be defined

The proposal discusses accidentally publishing metadata but not symlinks. Directory symlinks are not followed by Symfony Finder by default, but file symlinks and paths resolving outside _media need explicit tests.

For a directory declaring “everything here is public,” a safe rule is:

Copy regular files only, and never copy a source whose resolved path escapes the configured media root.

Is the cost-benefit analysis valid?

Broadly, but not as written.

Claim	Code-grounded assessment
Passthrough gives a better mental model	Valid, and Hyde’s own docs already say “all files” are copied in managing-assets.md and advanced-customization.md.
The allow-list has a high implementation burden	Overstated. Current discovery is a small use of an existing finder.
The allow-list has ongoing maintenance cost	Directionally true, but historically modest: the core list has existed since 2022 and appears to have gained only WebP.
Copy-with-exclusions has low implementation cost	Understated. Pattern semantics, dotfiles, validation, realtime serving, tests, config migration, and dashboard behavior all need work.
Existing users mostly gain functionality	Usually true, but users who deliberately narrowed media_extensions may unexpectedly publish files. That is a potentially security-relevant migration.
Asset validation can remain unchanged	False for excluded-but-existing assets.
Copying archives and other arbitrary assets is straightforward	Functionally yes, but the current transfer implementation is not suitable for large files.
Ecosystem comparison supports passthrough	Valid. Astro says public/ files are copied untouched, and Hugo says static/ is copied to public/. Eleventy does require explicit passthrough registration, as the document states. Astro documentation, Hugo documentation.

The comparison with Jekyll is also fair: its broader source tree copies ordinary static files but excludes specially named and hidden paths unless explicitly included. Jekyll documentation.

Will it still feel like Hyde?

Yes—more than the current behavior—provided the edge cases are made coherent.

“Put a static asset in _media; Hyde publishes it” is exactly the sort of convention-over-configuration contract Hyde should have. The current documentation already promises this, while the implementation quietly narrows it.

What would not feel like Hyde is:

• An excluded asset helper generating a broken link
• A file working in hyde serve but not in hyde build
• A large ZIP exhausting PHP memory
• Hidden-file behavior changing without a clear migration warning
• A sophisticated exclusion language users must understand for normal use

The advanced media_exclude setting is still Hyde-like because ordinary projects never need to touch it.

Recommended v3 design

I would proceed with Option 3, with these adjustments:

1. Keep MediaFile and all of its public asset API.
2. Stop using MediaFile::EXTENSIONS for discovery.
3. Keep the constant deprecated through v3 so old published config does not fatal.
4. Remove media_extensions from newly published configuration and document that existing settings no longer filter publication.
5. Define one path-based publication policy shared by discovery, asset references, copying, and the realtime compiler.
6. Use root-relative, normalized / paths for exclusions and precisely document basename versus path patterns.
7. Keep Symfony’s VCS exclusion rather than recreating .git/**, .hg/**, and .svn/**.
8. Decide explicitly whether dotfiles are supported. If yes, enable their discovery and selectively exclude .gitkeep, .DS_Store, Thumbs.db, and ._*.
9. Stream files with Filesystem::copy() rather than loading complete contents into memory.
10. Make explicit asset references fail helpfully when the requested file is excluded.
11. Avoid eagerly hashing every discovered file during Markdown processing.
12. Test build/serve parity, symlinks, hidden directories, excluded references, custom media directories, and large binary assets.

The migration guide also needs to address users who treated media_extensions as a security allow-list. A pure positive exclusion list cannot easily preserve “publish only PNG and JPG” unless the pattern language supports negation or an advanced include policy remains available.

So: the proposal has the correct product conclusion, and it will feel more like Hyde. But this is a medium cross-cutting framework change, not merely deleting EXTENSIONS and adding four filename checks.

[emmadesilva]

Follow up from ChatGPT after giving deep research chat the AI resonse

Yes. This materially corrects the original analysis.

The earlier recommendation reached the right product conclusion, but for the wrong-sized implementation model. Hyde is not copying an opaque directory tree; it is discovering MediaFile objects that feed several public and internal systems. The real decision is:

Should Hyde’s shared asset discovery and publication policy remain extension-based, or should _media designate publication intent by directory?

Taking the code findings you supplied as accurate—I could not independently retrieve the current GitHub files in this session—the best answer is still directory-based publication, but implemented as a coordinated asset-system change.

Revised verdict

For HydePHP v3:

• Keep MediaFile.

• Make _media passthrough-by-default for new projects.

• Replace extension-based discovery with a centralized, path-based publication policy.

• Preserve current hidden-file and VCS behavior initially.

• Keep MediaFile::EXTENSIONS as deprecated compatibility API.

• Preserve the old hyde.media_extensions behavior for upgraded projects when that configuration key is still present.

• Use exclusions only as an advanced publication policy, not as ad hoc checks in the copying task.

The extension constant has little remaining value as Hyde’s definition of a publishable asset. It does retain value temporarily for backward compatibility.

What the constant is actually buying today

The current extension list provides four benefits:

1. It limits the number of discovered objects.

2. It bounds hashing, dashboard enumeration, and Markdown-processing work.

3. It prevents arbitrary non-matching files from reaching the output.

4. It gives existing users a crude publication allow-list.

Only the fourth benefit is strategically important.

The performance benefits can be achieved more directly through lazy hashing, efficient copying, and better Markdown matching. The safety benefit is weak because _media is already documented and understood as a public-assets directory. An extension is not a reliable security classification anyway: a harmless-looking extension can contain sensitive data, while legitimate PDFs, fonts, maps, manifests, archives, and other downloads are currently omitted.

The allow-list is therefore solving several secondary implementation problems by imposing friction on the primary user workflow.

Cost-benefit assessment

Approach | Common-case DX | Upgrade safety | Build performance | Internal complexity | Long-term fit -- | -- | -- | -- | -- | -- Keep extension allow-list | Low | High | Good | Low | Low Discover every file with no policy | High | Low | Potentially poor | Medium | Medium Passthrough with exclusions added separately to each subsystem | Medium | Medium | Mixed | Very high | Low Central publication policy, passthrough by default | High | High | Good after supporting changes | Medium-high | High Passthrough for new projects, legacy allow-list compatibility for upgrades | High | Highest | Good after supporting changes | High initially | Highest

The final option has the best overall outcome for v3.

Its implementation is larger, but most of that work is correcting existing coupling and development/production inconsistency rather than complexity intrinsic to passthrough publication.

Recommended architecture

Introduce one framework-level concept responsible for deciding whether a source asset is publishable. For example:

final class MediaPublicationPolicy
{
    public function allows(string $relativePath): bool;
public function assertAllowed(string $relativePath): void;

public function files(): Collection;

}

The exact class name is secondary. The important property is that the same policy governs:

• Hyde::assets() and MediaFile::all()

• Build-time copying

• Hyde::asset() and MediaFile::get()

• Realtime asset serving

• Dashboard enumeration

• Markdown asset rewriting

The publication rule should not be duplicated between these systems.

Default v3 policy

For new v3 projects:

• Discover all regular files recursively.

• Normalize paths relative to the configured media root.

• Preserve Symfony Finder’s existing VCS exclusions.

• Preserve current dotfile exclusion behavior.

• Do not follow directory symlinks.

• Preferably reject or skip all symlinks; at minimum, never accept a resolved target outside the media root.

• Apply configured path exclusions.

• Publish everything else.

Preserving current dotfile behavior is important. Enabling hidden-file discovery while changing extension discovery would combine two separate behavioral changes and could expose files that were never previously considered. Legitimate hidden assets can be addressed separately with an explicit, well-documented feature.

Because .gitkeep, .DS_Store, and ._* are already hidden, they do not need to be recreated in the default exclusion list. The useful defaults would likely be limited to visible OS noise such as:

[

'Thumbs.db',

'Desktop.ini',

]

This also demonstrates why the exclusion list should not be the central justification for the change. Most of the anticipated exclusions are already handled by the underlying finder.

Migration behavior

This is the area where I would be more conservative than the research agent’s recommendation.

Ignoring an existing hyde.media_extensions setting during an upgrade could cause files that users intentionally kept out of production to become public. Even in a major release, unexpectedly publishing files is a worse migration failure than retaining legacy behavior.

A safer v3 transition is:

New projects

The newly published configuration omits hyde.media_extensions, so passthrough mode is used.

Existing projects

When hyde.media_extensions is present in the application’s configuration, Hyde treats it as legacy allow-list mode and emits an actionable deprecation notice:

The hyde.media_extensions setting enables legacy extension-filtered media discovery. Remove this setting to use Hyde v3 passthrough media publication. It will be removed in HydePHP v4.

This produces several advantages:

• Existing projects do not silently publish additional files.

• New projects immediately receive the better convention.

• Users explicitly control when their project migrates.

• No complex negation syntax is needed merely to preserve old allow-list behavior.

• The constant and configuration can be cleanly removed in v4.

MediaFile::EXTENSIONS should remain through v3 because existing application configuration may reference it while PHP loads the config file. Mark it deprecated and clarify that it is not Hyde’s authoritative list of supported assets.

MediaFile remains essential

MediaFile is not merely a discovery result. It is the abstraction through which Hyde supplies:

• Normalized source and output paths

• URLs

• Existence checks

• File metadata

• Cache-busting

• Asset collections and helpers

Removing or renaming it would create public API churn with no meaningful benefit.

The correct conceptual split is:

• MediaFile: a static asset value object

• MediaPublicationPolicy: whether that asset belongs in the generated site

• Capability-specific checks: whether an asset can be previewed, edited, rewritten as an image, or otherwise processed

The current extension constant should not be reused for those capability checks. CSS and JavaScript in the list already demonstrate that it is not an image-support list. Dashboard editing and Markdown image rewriting should each define the exact capabilities they support.

Required supporting changes

1. Fix excluded asset validation

The publication policy must be checked by explicit asset resolution.

An excluded but existing file must not produce a valid-looking URL to a file that will never be built. The preferred behavior is an actionable exception, for example:

The media file private/report.pdf exists but is excluded from publication by hyde.media_exclude.

Explicit references should not override exclusions. Otherwise exclusions cease to describe the generated output reliably.

2. Stream or directly copy files

The transfer task should not read entire files into PHP strings.

Use the filesystem’s direct copy operation, verify its result, and report the source and destination when it fails. This is needed independently of discovery semantics, but passthrough publication makes the weakness much easier to encounter through videos, archives, PDFs, and other large downloads.

3. Make hashing lazy

Broad discovery should not mean broad hashing.

The Markdown processor should first determine whether an asset path is actually present in relevant HTML, and only then create a cache-busted link. Better still, it should extract image references and resolve those references rather than iterating over every asset.

For example, the order should effectively be:

if (! str_contains($html, $file->getSourcePath())) {

continue;

}

$html = str_replace(

$file->getSourcePath(),

$file->getLink(),

$html,

);

The crucial detail is that getLink() must not be evaluated before the cheap occurrence check.

Arbitrary PDFs and ZIP files should not become candidate Markdown images merely because they are now discoverable.

4. Guarantee build/serve parity

The realtime compiler must use the same publication policy as the production build.

A file should never:

• Work under hyde serve but disappear under hyde build

• Be excluded from production but remain accessible during development

• Be rejected by Hyde::asset() while still being directly served

If booting the complete framework for every media request would damage the realtime compiler’s fast path, the policy can be initialized once and cached. The requirement is shared semantics, not necessarily shared runtime execution on every request.

5. Adjust dashboard terminology and capabilities

The dashboard will become an asset library containing images, fonts, documents, archives, data files, and source maps.

It does not need a major redesign, but it should:

• Use “asset” rather than “image” where appropriate

• Distinguish previewable and editable files

• Avoid presenting an edit action that predictably throws

• Provide recognizable placeholders for common document and font categories

6. Define symlink behavior

The least surprising v3 rule would be:

Media discovery does not follow symlinks.

Supporting in-root file symlinks could be added later, but it creates platform differences and complicates containment guarantees. At an absolute minimum, resolved sources outside the media root must never be published.

Exclusion semantics

The exclusion language should remain deliberately small:

• Patterns match normalized /-separated paths relative to the media root.

• A basename pattern such as Thumbs.db matches that filename at any depth.

• A path pattern such as private/ matches from the media root.

• Matching is deterministic across Windows and Unix.

• Negation is not supported initially.

• Excluded explicit references throw rather than silently produce broken links.

Negation becomes unnecessary for migration if legacy extension filtering remains available during v3.

The configuration could look like:

'media_exclude' => [

'Thumbs.db',

'Desktop.ini',

'private/',

],

Suggested implementation order

1. Add the centralized publication policy while preserving current extension behavior.

2. Route discovery, asset lookup, copying, and realtime serving through it.

3. Add tests proving current behavior remains stable.

4. Add passthrough mode and exclusions.

5. Make passthrough the default when no legacy media_extensions key exists.

6. Replace in-memory transfer with direct copying.

7. Make Markdown hashing and rewriting lazy.

8. Update dashboard capability handling.

9. Add migration documentation and deprecations.

This ordering prevents the behavioral change from being mixed with an untested architectural rewrite.

Minimum test matrix

The v3 change should prove:

• PDF, JSON, WOFF2, ZIP, and nested arbitrary files are discovered and copied in passthrough mode.

• Existing extension-filtered projects retain their current output.

• Removing media_extensions enables passthrough behavior.

• Custom exclusions affect discovery, copying, helpers, dashboard results, and realtime serving equally.

• Referencing an excluded file throws an actionable exception.

• Missing files retain the current helpful failure behavior.

• Hidden files and VCS directories retain their existing behavior.

• Symlinks cannot publish content outside _media.

• Large files are copied without calling getContents().

• Unreferenced large assets are not hashed during Markdown processing.

• Development and production expose the same asset set.

• Custom source and output media directories still work.

• MediaFile::EXTENSIONS remains accessible for old configuration files and is marked deprecated.

Final recommendation

The product decision should be approved, but described accurately:

In HydePHP v3, _media becomes a passthrough asset directory for new projects. Hyde continues to represent published assets through MediaFile, but publication eligibility is determined by a shared path-based policy instead of a built-in extension taxonomy. Existing projects that retain hyde.media_extensions continue using legacy filtering during v3 to avoid unexpectedly publishing files.

So, there is no compelling long-term value in MediaFile::EXTENSIONS as the default publication boundary. Its value in v3 is compatibility and safe migration. The winning design is not “copy everything”; it is discover and publish everything intentionally placed in _media, consistently and efficiently, subject to one explicit policy.