{"id":45919819,"url":"https://github.com/troychaplin/smart-media-replacement","last_synced_at":"2026-02-28T08:36:31.336Z","repository":{"id":297140987,"uuid":"995777622","full_name":"troychaplin/smart-media-replacement","owner":"troychaplin","description":"An experimental plugin for WordPress that provides a simplistic way to replace an existing media file and maintain its existing URL.","archived":false,"fork":false,"pushed_at":"2026-01-23T12:13:04.000Z","size":4625,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T22:13:26.423Z","etag":null,"topics":["media-library","wordpress-plugin"],"latest_commit_sha":null,"homepage":"https://wordpress.org/plugins/smart-media-replacement/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/troychaplin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-04T02:00:46.000Z","updated_at":"2025-11-18T00:08:30.000Z","dependencies_parsed_at":"2025-07-12T14:26:47.432Z","dependency_job_id":"203f4437-1eed-4877-af4e-41c9b51faa4d","html_url":"https://github.com/troychaplin/smart-media-replacement","commit_stats":null,"previous_names":["troychaplin/replace-media","troychaplin/smart-media-replacement"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/troychaplin/smart-media-replacement","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fsmart-media-replacement","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fsmart-media-replacement/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fsmart-media-replacement/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fsmart-media-replacement/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/troychaplin","download_url":"https://codeload.github.com/troychaplin/smart-media-replacement/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fsmart-media-replacement/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29928999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["media-library","wordpress-plugin"],"created_at":"2026-02-28T08:36:29.381Z","updated_at":"2026-02-28T08:36:31.323Z","avatar_url":"https://github.com/troychaplin.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/banner-772x250.png\" alt=\"Smart Media Replacement Plugin Banner\" style=\"width: 100%; height: auto;\"\u003e\n\n# Smart Media Replacement Plugin\n\nA WordPress plugin that allows you to replace media files while maintaining their original URLs and metadata. This is particularly useful for updating files like PDFs, images, or other documents without breaking existing links.\n\n## Features\n\n- Replace media files while maintaining original URLs\n- Preserves all existing links (both internal and external)\n- Maintains file metadata and relationships\n- Simple and intuitive interface in the WordPress Media Library\n- Supports all file types supported by WordPress\n- **Validates file names to prevent accidental URL changes**\n- **Enforces dimension matching for images to prevent layout issues**\n- **Automatically handles WordPress scaled images**\n- **Validates file type matching to ensure consistency**\n- AJAX-based replacement with error handling\n\n## Installation\n\n1. Download the plugin files\n2. Upload the `smart-media-replacement` folder to the `/wp-content/plugins/` directory\n3. Activate the plugin through the 'Plugins' menu in WordPress\n\n## Usage\n\n1. Go to the WordPress Media Library\n2. Find the file you want to replace\n3. Click on the file to view its details\n4. Look for the \"Replace File\" button in the attachment details\n5. Click \"Replace File\" and select your new file\n6. The replacement will happen automatically\n\n### Important Requirements\n\n#### Filename Matching\n- **The new file MUST have exactly the same filename as the original file**\n- Example: If your original file is `logo.png`, your replacement must also be named `logo.png`\n- If filenames don't match, you'll receive an error with the required filename\n\n#### Image Dimensions (Images Only)\n- **For images, the replacement MUST have identical dimensions (width × height)**\n- This prevents layout issues where images might break your design\n- Example: If your original image is 1200×800px, your replacement must also be 1200×800px\n\n#### WordPress Scaled Images\n- If WordPress automatically scaled your original image (large uploads), the plugin handles this automatically\n- You should upload a file with the **original** filename (without `-scaled`)\n- Example: If you see `photo-scaled.jpg` in the media library, upload your replacement as `photo.jpg`\n- The plugin will show you the correct filename if there's a mismatch\n\n#### File Types\n- The replacement file must be the same file type as the original\n- Example: You cannot replace a `.jpg` with a `.png`\n- The plugin validates MIME types to ensure consistency\n\n## Troubleshooting\n\n### \"The new file must have the same name as the original file\"\n- Rename your replacement file to match the original filename exactly\n- Check for the correct file extension\n\n### \"The replacement must have the exact same dimensions\"\n- Resize your replacement image to match the original dimensions\n- Use image editing software to verify dimensions before uploading\n\n### \"File type mismatch\"\n- Your replacement file must be the same file type as the original\n- Check that you're not trying to replace a JPEG with a PNG, or a PDF with a DOCX\n\n### \"This image was automatically scaled by WordPress\"\n- Your original image was larger than WordPress's threshold (typically 2560px)\n- Upload your replacement with the original filename (shown in the error message)\n- The plugin will handle the scaling automatically\n\n### \"You do not have permission to edit this attachment\"\n- You must have permission to edit the specific media file\n- Contact your site administrator if you believe you should have access\n\n### Button not appearing\n- Make sure you're viewing the attachment details (click on a media item)\n- Clear your browser cache\n- Check that you have permission to edit media files\n\n## For Developers\n\n### Hooks and Filters\n\n#### Filters\n\n**`smart_media_replacement_enforce_dimensions`**\n\nAllows you to disable or customize dimension enforcement for specific attachments.\n\n```php\n/**\n * Disable dimension enforcement for specific attachments.\n *\n * @param bool $enforce       Whether to enforce dimensions. Default true.\n * @param int  $attachment_id The attachment ID being replaced.\n * @return bool\n */\nadd_filter( 'smart_media_replacement_enforce_dimensions', function( $enforce, $attachment_id ) {\n\t// Allow flexible dimensions for attachment ID 123\n\tif ( $attachment_id === 123 ) {\n\t\treturn false;\n\t}\n\treturn $enforce;\n}, 10, 2 );\n```\n\n#### Actions\n\n**`smart_media_replacement_file_replaced`**\n\nFires after a media file has been successfully replaced.\n\n```php\n/**\n * Perform custom actions after file replacement.\n *\n * @param int    $attachment_id   The ID of the attachment that was replaced.\n * @param string $new_file_path   The full path to the new file.\n */\nadd_action( 'smart_media_replacement_file_replaced', function( $attachment_id, $new_file_path ) {\n\t// Clear custom caches\n\twp_cache_delete( 'my_custom_cache_' . $attachment_id );\n\t\n\t// Notify external services\n\tdo_something_custom( $attachment_id );\n\t\n\t// Log the replacement\n\terror_log( \"Media file replaced: {$attachment_id} -\u003e {$new_file_path}\" );\n}, 10, 2 );\n```\n\n### Building from Source\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   npm install\n   composer install\n   ```\n3. Build the JavaScript files:\n   ```bash\n   npm run build\n   ```\n\n### File Structure\n\n- `Functions/` - PHP classes and WordPress hooks\n  - `ManageMedia.php` - Core replacement functionality and AJAX handlers\n- `src/` - JavaScript source files\n  - `replace-media.js` - Frontend interaction and file upload handling\n- `build/` - Compiled JavaScript files (generated by webpack)\n- `vendor/` - Composer dependencies\n\n### Development Notes\n\n- The plugin uses WordPress's native media handling functions\n- File validation happens server-side for security\n- The JavaScript uses the WordPress i18n system for translations\n- PHPCS is configured with WordPress coding standards\n\n## Requirements\n\n- WordPress 6.6 or higher\n- PHP 7.0 or higher\n- User must have `edit_post` capability for the specific attachment\n\n## Privacy\n\nThis plugin:\n- Does not collect or transmit any user data\n- Does not use cookies\n- Only processes files locally on your server\n- Does not communicate with external services\n\n## Support\n\nFor support, please open an issue on the GitHub repository.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## License\n\nThis plugin is licensed under the GPL v2 or later.\n\n## Credits\n\nDeveloped by Troy Chaplin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroychaplin%2Fsmart-media-replacement","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftroychaplin%2Fsmart-media-replacement","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroychaplin%2Fsmart-media-replacement/lists"}