Extension talk:Layers

Welcome to my Layers extension. Please help me identify issues and opportunities for improvement. Pvodrazka (talk) 03:17, 18 December 2025 (UTC) Reply

The documentation states that "composer install" and "npm install" both need to be called for this extension. Are both of those really necessary? It would be great to eliminate one or both of these requirements, especially the second one. Yaron Koren (talk) 17:38, 31 December 2025 (UTC) Reply

Hi Yaron. You do not need those. I will update the documentation. Those are useful for development and testing, not for a production install.

As a test, I spun up Mediawiki 1.43 in Docker, extracted the extension, added entries to LocalSettings.php, ran mw-config to update tables, and the extension works. No composer or npm.

Thank you for pointing this out. Pvodrazka (talk) 05:24, 1 January 2026 (UTC) Reply

Good to hear! Yaron Koren (talk) 06:22, 2 January 2026 (UTC) Reply

Using the examples from the extension page to show images doesn't work (1.43 branch) with the layerslink parameter:

[[File:Anatomy.png|thumb|layers=anatomy|layerslink=viewer]]
[[File:Diagram.png|thumb|layers=labels|layerslink=editor]]

Doing that shows the layerslink text under the thumbnail (i.e. "layerslink=viewer"). Displaying the images without thumb does work. Bryandamon (talk) 20:53, 31 December 2025 (UTC) Reply

I just tested this and can confirm that with 'thumb' the 'layerslink=' displays as a caption.

I will try to fix this ASAP.

Thank you for posting. Pvodrazka (talk) 05:28, 1 January 2026 (UTC) Reply

This is now fixed in 'main' and 'REL1_43'.

Thank you for the feedback. I appreciate it. Pvodrazka (talk) 05:50, 1 January 2026 (UTC) Reply

The creation and editing of layers seems to work great. But actually displaying those layers seems to have a bug - it looks to me like they only get displayed when "layers=default" is specified; any actual layer name gets ignored. Do you see this behavior as well? Yaron Koren (talk) 07:04, 2 January 2026 (UTC) Reply

I am not seeing this. I have multiple instances the same image on a page with a different layer set called for each. I have different variations of 'layerslink=' as well. All seem to work correctly for me.

I wonder if others are seeing this.

Yaron, which version are you testing, and what database do you use? Pvodrazka (talk) 01:59, 3 January 2026 (UTC) Reply

This is using the latest Layers code (I just tested it again), on MW 1.43, with MySQL 8. I can try to debug it locally if you can't reproduce this issue. Yaron Koren (talk) 17:37, 5 January 2026 (UTC) Reply

Alright, I think I figured out the problem: I was specifying layer names, but what I needed to specify was the layer set name. (I wasn't really even aware of the layer sets before.) At the very least, I think the documentation should be improved; but I think there's a case for renaming the "layers=" parameter to "layer set=". (Assuming you can specify only one.) Yaron Koren (talk) 19:05, 5 January 2026 (UTC) Reply

Thanks Yaron. I can make this change. 'layerset=' is more intuitive.

I may keep 'layers=' for backwards compatibility so users don't have to go back and edit existing pages.

I'm currently working on adding a new 'custom shape' tool, but I will try to add this to the next build.

Thanks for the feedback Yaron. BTW, if you get a chance, I would love your feedback on the project, specifically an honest review of the codebase. I know I'm asking a lot. I really value your opinion. Pvodrazka (talk) 20:31, 5 January 2026 (UTC) Reply

As per your recommendation, the default method to invoke a layer set is now 'layerset=layer set name', while 'layers=layer set name' remains for backwards compatibility. Thanks Yaron. Pvodrazka (talk) 14:51, 6 January 2026 (UTC) Reply

Great! Yaron Koren (talk) 15:45, 6 January 2026 (UTC) Reply

I installed the extension earlier today by downloading the .zip archive from GitHub which theoretically should be the "main" branch, yet it identifies itself in Special:Version as REL1_43. This led me to report bug #33, which I presume it's unrelated to this.

Just in case I did something wrong I decided to try following the instructions in the extension page here using Git to clone the repository instead. Nothing changed, but just in case I tried to reapply "php run update.php" and got this error:

...
Applying constraints for `layer_sets`...
Wikimedia\Rdbms\DBQueryError from line 1232 of /srv/www/lighttpd/w144/includes/libs/rdbms/database/Database.php: Error 1826: Duplicate CHECK constraint name 'chk_ls_size_positive'
Function: MediaWiki\Extension\Layers\Database\LayersSchemaManager::runCheckConstraintsPatch
Query: ALTER TABLE `layer_sets` ADD CONSTRAINT chk_ls_size_positive CHECK (ls_size >= 0)
#0 /srv/www/lighttpd/w144/includes/libs/rdbms/database/Database.php(1216): Wikimedia\Rdbms\Database->getQueryException()
#1 /srv/www/lighttpd/w144/includes/libs/rdbms/database/Database.php(1190): Wikimedia\Rdbms\Database->getQueryExceptionAndLog()
#2 /srv/www/lighttpd/w144/includes/libs/rdbms/database/Database.php(647): Wikimedia\Rdbms\Database->reportQueryError()
#3 /srv/www/lighttpd/w144/includes/libs/rdbms/database/DBConnRef.php(127): Wikimedia\Rdbms\Database->query()
#4 /srv/www/lighttpd/w144/includes/libs/rdbms/database/DBConnRef.php(302): Wikimedia\Rdbms\DBConnRef->__call()
#5 /srv/www/lighttpd/w144/extensions/Layers/src/Database/LayersSchemaManager.php(116): Wikimedia\Rdbms\DBConnRef->query()
#6 /srv/www/lighttpd/w144/includes/installer/DatabaseUpdater.php(554): MediaWiki\Extension\Layers\Database\LayersSchemaManager::runCheckConstraintsPatch()
#7 /srv/www/lighttpd/w144/includes/installer/DatabaseUpdater.php(511): MediaWiki\Installer\DatabaseUpdater->runUpdates()
#8 /srv/www/lighttpd/w144/maintenance/update.php(198): MediaWiki\Installer\DatabaseUpdater->doUpdates()
#9 /srv/www/lighttpd/w144/maintenance/includes/MaintenanceRunner.php(694): UpdateMediaWiki->execute()
#10 /srv/www/lighttpd/w144/maintenance/run.php(51): MediaWiki\Maintenance\MaintenanceRunner->run()
#11 /srv/www/lighttpd/w144/maintenance/run(3): require('...')
#12 {main}

I'm not sure if this is the extension's fault or something else so I'm reporting it here. The database engine is MariaDB 11.1.2 in case it is relevant. Tactica (talk) 15:54, 2 January 2026 (UTC) Reply

Thanks Tactica, I will look at the upgrade script later today. Thanks for posting the error dump. This helps a lot. Pvodrazka (talk) 21:21, 2 January 2026 (UTC) Reply

MySQL uses error code 3822 for duplicate CHECK constraints

MariaDB uses error code 1826 for duplicate CHECK constraint names

The code was only checking for MySQL's error code (3822), so when running on MariaDB it threw the exception instead of gracefully handling the "already exists" case.

Now the code checks for both error codes using in_array( (int)$matches[1], [ 3822, 1826 ] ).

I will push this change in the next update. This issue might have affected other users too. I hope this resolves it.

Thank you for testing the extension and for posting the bug. Pvodrazka (talk) 21:27, 2 January 2026 (UTC) Reply

I can confirm the problem is gone with the current version on Git. Tactica (talk) 01:19, 5 January 2026 (UTC) Reply

Since you asked above, here are some of my recommendations for how to improve the Layers extension. It already provides great functionality, but there are ways I think it can be taken to the next level.

The biggest change I would argue for is putting all the layers information into "slots" of the relevant File: wiki page (using Multi-Content Revisions), rather than storing it in the database. This would allow easy viewing of the entire history of changes to the annotations, just by viewing the page history, rather than the current approach, which, though pretty amazing as an interface, allows for viewing change history only piecemeal, and (if I understand it correctly) is not viewable to non-editors. I'm actually not sure if this would be a major engineering challenge - the layers information is already already stored as JSON, I believe, which means that it's ultimately just a matter of putting the JSON in a different place. (I'm imagining a different "slot" for each layer set.) Perhaps an engineering challenge would be making the diffs look more graphically interesting than just the default textual one, which would just show changes to the JSON, but even that default approach would offer more information on changes over time than what currently exists.

Such a change would, I think, require moving all the revision-handling stuff out of the Layers interface and into the general MediaWiki interface. That would mean removing the "Revision" dropdown from the Layers interface, as cool as it is, and would mean allowing both the "action=editlayers" and "layerset=..." URL parameters to take in an "oldid=" parameter, so that editors can use the standard page history to get to a specific revision instead. Also, there should possibly be a "Summary" field for every revision save (displayed either next to the "Save" button, or as a popup after "Save" is clicked), so that the revision history is easier to understand.

Overall, most of my recommendations involve a "less is more" approach, so that users (and developer(s)) can focus on the stuff that truly matters:

• Remove the "createlayers" permission. I don't know why someone would be allowed to create new layer sets but not edit existing layer sets, or vice versa. Is the idea that some users can be trusted to create their own annotations, but not edit others' work? If so, it poses a problem if such a user creates their own layer set, then leaves and returns later, wanting to change something in what they created. Ultimately, it feels to me like it's all the same thing - unless there's a way to allow users to only edit layer sets they created, which could be a more useful approach. (This might all be true for "managelayerlibrary" as well - I don't know what that does, though.)
• Get rid of the "layerslink" parameter. People already have an expectation of what happens when they click on an image - they will go to the "File:" page for that image. I think that's what should be done here - though it would be great if a "&layerset=..." were added to the URL, so people could see what they saw before. Then, of course, if they want to edit the image, they can click on "Edit Layers".
• Get rid of the "Cancel" button in the interface. The "X" at the top already accomplishes the same thing, I think, and it's clearer.
• The "Toggle lock" feature feels unnecessary also. Why lock a layer? Actually, I'm not even sure what this feature does - it looks like layers can still be edited even when they're locked.
• A lot of the global variables seem unnecessary as well. Why have a maximum number of layers per set, and why should it be different from one wiki to another? I can understand having a maximum byte size, so users don't overload the system, accidentally or on purpose, but the three non-byte settings feel like they could be removed.

Conversely, it would be great to add one thing: a list of layer sets, displayed at the top of every file page that has layer sets defined for it. Each one would be a link to the "?layerset=..." URL, so that users can just click on any of them to see that specific annotation. I think it would add a lot of clarity, especially for non-editors but also for editors.

Finally, some other suggested changes:

• It's confusing right now that, when you create a new layer set, it starts off by default looking like whatever layer set you were just viewing/editing. Presumably it should start out as blank.
• "Edit Layers" should be "Edit layers", in keeping with MediaWiki style.

These are a lot of recommendations - feel free to take or not take any of them. And others can feel free to weigh in also on any of these. Yaron Koren (talk) 16:32, 6 January 2026 (UTC) Reply

Thank you so much for this thoughtful feedback. Here's my thinking on each point:

• Multi-Content Revisions (Slots):
  • This is an interesting architectural direction worth exploring for a future major version. The current database approach was chosen because layer sets are per-image (an image can appear across many wiki pages), and we need to support multiple named sets per image, each with their own revision history. MCR slots would require careful design to handle this granularity, but I'm open to investigating it for v2.0. In the meantime, the revision dropdown provides focused control for annotation versioning. I do agree that it's not perfect.
• Permissions - The current model:
  • createlayers — Create layer sets and edit/delete your own
  • editlayers — Edit anyone's layer sets, delete your own
  • managelayerlibrary — Full admin (delete any layer set)
  • I agree this could be simpler. I'll consider consolidating (keep editlayer and remove createlayers) in a future release.
• 'layerslink' parameter:
  • I'll keep this for specialized workflows (work instructions, Page Forms integration, lightbox viewing), but the default behavior (omitted) already links to the File: page as expected. I'll improve the documentation to clarify use cases.
• Cancel button:
  • Agreed — redundant with the X. I'll remove it.
• Lock layer:
  • This prevents accidental movement while editing other layers (standard in Photoshop/Figma). If it's not working correctly, that's a bug I'll fix. I'll also improve the visual feedback.
• Global variables:
  • I'll keep $wgLayersMaxBytes and $wgLayersMaxRevisionsPerSet for storage management, but I'll consider hardcoding the others or providing better defaults. The configurability was intended to help enterprise wikis with specific needs.
• Layer set list on File: pages:
  • Great suggestion! I'll add a collapsible list showing available layer sets with links to ?layerset=setname. This will significantly improve discoverability.
• New layer set starting blank:
  • Agreed — copying the previous set is confusing. I'll change this to start with a clean canvas. Users can use export/import if they want to reuse elements.
• "Edit layers" capitalization:
  • Good catch — I'll change to sentence case to match MediaWiki conventions.

Thank you for taking the time Yaron. I really do appreciate it. Pvodrazka (talk) 21:40, 6 January 2026 (UTC) Reply

Great, I'm glad that you agree with some of these suggestions. As I said, it's entirely up to you which of these you want to take and which not - you of course know much more about the code and functionality than I do. I didn't know, for example, that the "createlayers" permissions lets users edit their own layer sets - which already sounds better. (Though the documentation for it should probably be improved.) I was wondering about that Page Forms integration thing - is the idea that users are supposed to edit the annotations of images displayed within a page, in between filling out the form? And does this actually work in practice? Yaron Koren (talk) 00:06, 7 January 2026 (UTC) Reply

Yes, we use Page Forms and Cargo (thank you for the amazing extensions!) on my company's wiki for hosting SOPs, which are image-heavy. I've tried to make SOP creation as simple as possible, letting users focus on content rather than formatting. We are in the process of developing a corporate wiki to host other documents like Work Instructions.

A recurring pain point: adding even a simple arrow to an image requires editing it in an external program and re-uploading. Often the same base image needs different markups for different contexts, and once the SOP is finalized, the original source files get lost. If the process changes, entirely new images are needed rather than just updating the annotations. This was my motivation to develop this extension.

For Page Forms integration, I haven't fully figured out the linking workflow yet. Since the image target is already programmatic, I could conditionally show a link to the editor (and incremental layer set) only when the image exists using {{#ifexist:...}}. But there's still work to do first - I may have some feature requests for you down the road. Pvodrazka (talk) 02:56, 7 January 2026 (UTC) Reply