Feature Requests – Adaptation for Educational Institution Use (Adult Learning Center)

[nickun]

Hello,
We are currently trying to adapt Pinakes for use at an Adult Learning Center, where it would serve as a system for managing educational literature and tracking borrowing/returns by both teachers and students. During this process, we've run into several limitations that currently prevent full deployment. We'd like to request improvements or ask whether workarounds already exist for the following:

1. Subtitle not shown in search results
   When searching for a book by title, the results list displays only the main title, not the subtitle. In our collection, a base textbook and its accompanying workbook often share the exact same title and are distinguished only by subtitle (e.g., "Workbook" vs. no subtitle). This makes it impossible to tell them apart in the search results, leading to a high risk of selecting the wrong item.
   Request: Please add the subtitle field to the search results list (or make it optionally visible/configurable), so that items with identical titles can be distinguished.
2. No practical way to use unique physical copy numbers
   The system supports registering individual physical copies of a book with unique numbers, which is exactly what we need for accurate inventory tracking. However, there is currently no way to make practical use of this feature:

• The label printing function does not include the unique copy number on the printed label.
• There is no way to register a borrowing/return transaction against a specific physical copy — only against the general book/ISBN record.
  Request: Please add the unique copy number to the printable labels, and add the ability to select/scan a specific physical copy (not just the general title) when registering a loan or return.

3. Need for a streamlined, code-based borrowing/return workflow with camera scanning
   Building on point 2 — once individual physical copies can be identified by a unique code (e.g., barcode or QR code) on the printed label, we would need a simple and transparent workflow for registering borrowing and returns using that code, ideally including:

A dedicated "Scan" button next to the code input field.
The ability to use a device's camera as a barcode/QR scanner directly in the browser, without requiring external hardware.

For reference, the zxing-wasm JavaScript library has worked well for this kind of in-browser camera scanning in our testing, and might be a useful option to consider for implementation.

Thank you for considering these requests. We believe these changes would make the system significantly more practical not only for our use case but for any library managing physical copies with unique identifiers. We're happy to provide more details about our specific workflow or test any changes if that would help.
Best regards,
Nikola

[fabiodalez-dev]

All three are done and merged:

1. Subtitle in search results — the results list now shows the subtitle under the title, so a base textbook and its workbook are easy to tell apart.

2. Copy numbers you can actually use — each physical copy's inventory number now prints on its own label as a Code128 barcode, and you can register a loan or a return against a specific copy by that code, not just by the title.

3. Camera scan — a "Scan" button sits next to the code field on both the loan and the return form, using the device camera right in the browser, no external hardware. zxing-wasm was a good call — that's what I ended up using.

It's all on the main branch, so it lands in the next release (0.7.31) rather than something you can download today. One honest caveat: I could only test the scanner headless (no camera on my build machine), so the live decode I haven't run on real hardware yet — once it's out, tell me how it behaves on your devices.

The copy-tracking side is the part I most wanted to get right for a center like yours, so I'd really like to hear whether the label + scan flow matches how you track copies day to day.

[nickun]

Thank you! As soon as the release comes out, I'll immediately check how everything works.
Another question - does the "Remember me" checkbox on the login page affect anything? If I check it, the session still expires.

[fabiodalez-dev]

I'll check the "Remember me" checkbox. Should works as expected by I'll investigate the session...

[nickun]

Thank you for the improvements — printing labels with physical copy numbers instead of the EAN now works well.
While testing further, we found a few remaining issues with the "Create New Loan" workflow and the camera scanning module:

1. "Create New Loan" still requires searching by title/ISBN/EAN, even when the copy code is known
   In the "Create New Loan" form, the "Book – Search by title, ISBN or EAN" field is mandatory, even though there is a separate "Copy code (inventory)" field below it. This means that simply scanning or pasting the physical copy code is not enough to register a loan — the staff member still has to search for and select the book manually.
   This creates a real risk: it's possible to select a book in the search field that does not actually correspond to the physical copy code entered below, resulting in a loan registered against the wrong item.
   Request: Please combine these into a single field — e.g., "Search by title, ISBN, EAN, or Copy code (inventory)" — so that scanning/entering a copy code alone is sufficient to identify and register the correct book and copy, without a separate mandatory title search.
2. Subtitle still missing from search results in this form
   As a related note: the search field in "Create New Loan" also does not display the subtitle, even though it is shown in other parts of the system. Since we rely on the subtitle to distinguish between similarly titled items (e.g., a textbook vs. its workbook), this inconsistency increases the risk described above. Please ensure the subtitle is shown consistently across all search fields, including this one.
3. Camera scanner blocked by Permissions-Policy header
   The barcode scanning module fails to access the camera. The browser console shows the following error:
   [Violation] Permissions policy violation: camera is not allowed in this document.
   copy-scanner.bundle.js
   at: navigator.mediaDevices.getUserMedia(...)
   I traced this to public/index.php, where the response header is set as:
   php->withHeader('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
   This explicitly denies camera access for the entire document, which blocks the scanner from functioning.
   Request: Please update this header to allow camera access (e.g., camera=(self)) so that the in-browser barcode scanning feature can work as intended.
4. "Loan Details" page does not show the physical copy number
   On the "Loan Details" page, the physical copy number (inventory code) is not displayed, even when the loan is linked to a specific copy. This makes it impossible to verify at a glance which physical copy was actually borrowed, which is important for tracking and for resolving discrepancies during returns.
   Request: Please display the physical copy number on the "Loan Details" page whenever the loan is associated with one.
5. Return receipt PDF is missing subtitle and inventory code
   The PDF receipt generated after returning a book does not include the subtitle in the "Book Details" section, nor does it show the physical copy's inventory code, even when the loan was linked to a specific copy.

[nickun]

Here is another error:

[nickun]

In the file app/Views/prestiti/index.php the script "Auto-trigger PDF download after loan creation" has the comment that contains </script> which breaks html and shows the following:

if a future refactor ever lets a non-numeric // value through. var pdfId = 3; if (pdfId > 0) { var iframe = document.createElement('iframe'); iframe.style.display = 'none'; iframe.src = window.BASE_PATH + '/admin/loans/' + pdfId + '/pdf'; document.body.appendChild(iframe); // Clean up URL params after download triggers if (window.history && window.history.replaceState) { window.history.replaceState({}, '', window.BASE_PATH + '/admin/loans'); } } })();

[fabiodalez-dev]

All of this is in v0.7.31, out now.

Copy code alone identifies the book. On the Create New Loan form, entering or scanning a copy inventory code now resolves the book automatically and pins that exact copy. The title search is no longer something you have to do, and you can no longer end up with a loan registered against a book that doesn't match the scanned copy — the book field fills itself from the code, with a status line confirming the identified copy (and a warning if that copy isn't available).

Subtitle in the loan search. The book-search suggestions on that form now show the subtitle, so a textbook and its workbook are distinguishable there too. The loan details page and the receipt PDF also carry the subtitle and the physical copy inventory code.

Camera scanner. It was blocked by the Permissions-Policy response header (camera=()); it now allows the camera on the same origin, so the in-browser scanner works. One thing to check on your side: browsers only grant camera access over HTTPS (a secure context), so the scanner needs your instance to be served over https.

"Remember me". That checkbox was silently ignored due to a field-name mismatch — it is honoured again.

Update from the admin panel, or grab it here: https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.31

[fabiodalez-dev]

The "another error" — the block of raw JavaScript shown as text on the loans list after creating a loan — is fixed in v0.7.32. An inline script was being closed early by a comment that contained a literal script-closing tag, so the rest of the JS rendered as page text. It no longer does.

This is on top of the loan-workflow and camera-scanner fixes already in 0.7.31. https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.32

[nickun]

Overall we're very impressed — the system is now fully usable in our library. The camera scan module works like a charm, especially from a phone, and the loan/return workflow is intuitive for our staff. Thank you for the work on the previous fixes.
A few smaller improvements that would round things out nicely:

1. Ability to print a single copy label, not only all at once
   In the physical copies list for a book, the "Print copy labels" button works well but always prints all labels at once. When only one or a few specific labels are needed, the only option is to specify page ranges in the print dialog, which is inconvenient and error-prone.
   Request: Please add a "Print" action in the "Actions" column for each individual copy, allowing a single label to be printed on demand.
2. More flexible label size and content settings
   We use a Dymo LabelWriter 450 with "Small Name Badge" labels (89mm × 41mm). The closest built-in option is currently 70mm × 36mm ("Large internal labels"), which isn't an ideal fit.
   Request: Please add a custom/user-defined label size option (width × height), in addition to the presets.
   Additionally, we'd suggest adding checkboxes in the label settings to control which fields appear on the label — e.g.:

• Application name
• Book title
• Book subtitle
• Author with publisher
• Dewey code
  This would let us print only the fields we actually need, leaving more space for the barcode itself.

3. Language management — missing keys after updates
   Language handling has a few rough edges. We use Norwegian (nb_NO), which isn't a built-in language, so earlier we downloaded the English file (locale/en_US.json), translated it (with AI assistance) to nb_NO, and uploaded it — this worked well.
   Two issues came up since:

• After a subsequent update, our custom language file disappeared from the server entirely. We had to re-upload our own backup copy to restore it.
• The built-in languages now show as fully translated (e.g., 6500/6500 keys), while ours shows 5450/5450 — which is expected, but makes it hard to tell which of the newer keys are actually missing from our translation, since it reports 100% complete based on our older key count.

Request: Please ensure the "Download JSON" action always exports a complete file containing all current keys, with an empty string for any key that doesn't yet have a translation in that language. This would let us easily identify and fill in only the missing/new keys after each update, and would also prevent custom language files from being silently dropped during updates.

[fabiodalez-dev]

v0.7.33 is out with the three improvements from your last round:

• Print a single copy's label: each row in a book's physical-copies table now has its own print action — no more page-range juggling in the print dialog.
• Custom label size: you can enter width × height directly (your Dymo 89×41mm works), and content checkboxes let you choose which fields appear on the label (application name, title, subtitle, author+publisher, Dewey) — leaving more room for the barcode. Also: the publisher is no longer clipped off landscape labels.
• Language management: your custom nb_NO.json will no longer be deleted by updates, and "Download JSON" now exports every current application key, with an empty string for anything not yet translated — so after each update you can spot and fill exactly the new keys.

Update from the admin panel, or grab it here: https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.33

[fabiodalez-dev]

On Docker, don't patch files from sh — anything written to the container layer is lost the next time the container is recreated. The supported way to update is to move the container to the new image; your data is safe because it lives in the database and in the storage/uploads volumes:

docker compose pull && docker compose up -d
# or pin the version explicitly:
PINAKES_TAG=0.7.33 docker compose pull && docker compose up -d

For 0.7.32 → 0.7.33 that's all you need (this release has no database schema change, and bundled plugins are re-synced from the image at boot).

One gap I'm closing right now: until today, updating by pulling a new image did not apply pending database migrations (only the in-app updater ran them). I'm adding a migration runner to the image entrypoint, so after a pull the container applies any pending schema migrations automatically on boot — that makes docker compose pull a complete upgrade path from now on. I'll note here when the refreshed image is published.

About the 500 on /admin/updates: I could not reproduce it on clean 0.7.32 and 0.7.33 containers (the page loads fine in both, including with the 0.7.33 update offered), so I need the actual error from your instance. Could you run:

docker logs <app-container> --tail 50
docker exec <app-container> sh -c 'tail -50 storage/logs/app.log'

open /admin/updates once, and paste whatever PHP error/exception shows up? Also useful: which version you're currently on, and whether you previously updated by pulling a new image or via the in-app updater.

[fabiodalez-dev]

The refreshed image is published: fabiodalez/pinakes:0.7.33 (and :latest) now applies any pending database migrations automatically on boot, so from here on

docker compose pull && docker compose up -d

is a complete upgrade — code and schema. On the first boot it also heals any schema drift accumulated by past image-pull upgrades (it re-applies the idempotent migrations since 0.7.22 if no schema version is recorded yet). Details in the image README.

The /admin/updates 500 is still worth understanding — the logs I asked for above would tell me what's failing on your instance.

[nickun]

I successfully updated with docker compose pull command and now everything is fine, the Updates page is also working. Thanks.

[fabiodalez-dev]

One more image refresh (0.7.33 / latest, published a few minutes ago) with extra hardening around the boot-time migration runner, and a point I want to make explicit: updating the image cannot break or wipe an existing installation. I verified the exact scenario end-to-end before publishing: a 0.7.30 install with catalogue data, swapped to the new 0.7.33 image — books, users and settings all intact (they live in the database and in the storage/uploads volumes, which the container swap never touches), pending schema migrations applied automatically on boot, search working. A transient database hiccup at boot no longer prevents the container from starting either — the migration run just retries on the next boot.

So whenever you're ready:

docker compose pull && docker compose up -d

(never use down -v — the -v flag deletes volumes.)

And when you have a moment, the /admin/updates logs from my earlier message would still help me pin down that 500.

[nickun]

Unfortunately, I didn't save the log before the update, and now the log only shows after the docked pull.

[nickun]

Bug Report — Inconsistent/Unstable Generation of Physical Copy Numbers

We've found a bug in the generation of physical copy inventory codes when changing the "number of copies" for a book. The numbering becomes inconsistent and can eventually cause a database error.
Steps to reproduce:

1. Set number of copies to 1 → generates LIB-3
2. Change number of copies to 2 → generates an additional code, but leaves the old one instead of renumbering, resulting in LIB-3 and LIB-3-C2 (inconsistent naming pattern — one copy has a suffix, the other doesn't)
3. Change number of copies from 2 back to 1 → deletes LIB-3, leaving LIB-3-C2. This is the wrong end being trimmed — the last copy should be deleted, not the first.
4. Change number of copies from 1 to 2 again → results in an error:

   PHP message: [ERROR] Duplicate entry 'LIB-3-C2' for key 'uniq_numero_inventario' 
   in /var/www/pinakes/app/Models/CopyRepository.php:85

Root cause (as observed): The system doesn't consistently apply the -CX suffix to all copies, and removes/adds copies from the wrong end of the sequence, leading to naming collisions.
Suggested fix:

1. Always apply the -CX suffix to every copy, regardless of the total count (i.e., never leave the first copy without a suffix — it should be LIB-3-C1, not LIB-3).
2. When reducing the number of copies, always remove from the end of the sequence (highest number first), not the beginning.
3. When increasing the number of copies, generate new numbers by filling in any gaps starting from C1 upward, rather than always appending to the highest existing number.
4. To support this properly, consider adding a "Delete" action in the "Actions" column for each individual copy, so specific copies (including ones with existing loan history) can be removed deliberately rather than only via the count field — this would also make gap-filling behavior predictable and give staff explicit control.

[fabiodalez-dev]

Thank you for the testing you're doing — and sorry you hit this. You're right: this is a real bug, and it surfaces exactly through the multi-copy / per-copy-label flow you've been exercising. Thanks for reporting it so precisely; your root-cause analysis was spot on across all three points.

What was happening:

• Inconsistent suffix: a book created with 1 copy got a bare LIB-3, but the moment you added a 2nd copy the code switched to suffixes, giving LIB-3 + LIB-3-C2.
• Trim from the wrong end: reducing the count deleted the first copy in the list (LIB-3), leaving the higher-suffixed LIB-3-C2.
• Additive numbering → collision: new copies were numbered -C{currentCount+1}, so after the above, going 1 → 2 again regenerated LIB-3-C2, which already existed → Duplicate entry on the unique index.

The fix does what you suggested:

1. Uniform -C{N} on every copy — a single copy is now …-C1, never a bare base, so adding a second copy gives a consistent C1/C2 pair.
2. Reduce trims from the end — the most recently added, available copies go first (loaned/reserved copies are never touched).
3. Gap-filling, collision-free generation — new codes walk up from C1, reuse the lowest free index left by a removed copy, and every candidate is checked against the whole copies table, so a duplicate can no longer occur.

I reproduced your exact sequence (1 → 2 → 1 → 2) against the old code and got the identical Duplicate entry '…-C2' crash; the new code runs the same sequence cleanly, and it's covered by a regression test that replays those steps.

Note: this changes generation for new copies only — existing copies keep their current codes (renaming them would break labels you've already printed).

On your last point — a per-copy Delete action in the copy list, so specific copies (including ones with loan history) can be removed deliberately rather than only via the count field: good idea, I'll add it as a follow-up; it also makes the gap-filling predictable for staff. I'll follow up here when it ships.

[fabiodalez-dev]

This is out now in v0.7.34, along with the label-scaling fix you raised separately.

• Copy numbering — codes are a uniform -C{N} on every copy, reductions trim from the end, and additions gap-fill the lowest free index with a uniqueness check, so the Duplicate entry '…-C2' crash on the 1 → 2 → 1 → 2 sequence can't happen anymore. Existing codes are left as they are (printed labels stay valid).
• Label content scaling — text and barcode now scale to fill the label area (centered, auto-fitting the width) instead of staying a fixed size amid growing margins, and there's a new Inner padding (mm) field in Settings → Labels.

Both were verified end-to-end, including a real 0.7.33 → 0.7.34 upgrade through the admin updater.

Since you're on Docker: the fabiodalez/pinakes:0.7.34 image is auto-building right now and will be on Docker Hub shortly — once it's up, docker compose pull && docker compose up -d moves you across (your data lives in the DB and volumes, so the swap is safe). If you'd rather not wait, the in-app updater (Admin → Updates) already offers 0.7.34.

Release: https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.34

[nickun]

Feedback — Label Content Scaling

The barcode label generation module has improved a lot — thank you. One remaining issue with the label content configuration:
Label content does not scale with label size
The content configuration correctly lets us choose which fields to display on the label, but the displayed elements themselves don't scale to fit the available space. When adjusting label dimensions, only the margins/whitespace around the content increase — the text and barcode elements stay a fixed size, so the label area isn't used efficiently, especially on smaller or larger label formats.
Request: Please have the content scale proportionally (and center) to fill the label area based on its actual dimensions, rather than keeping fixed-size elements with growing margins. Additionally, it would help to add configurable indentation/padding parameters in the label settings, so the layout can be fine-tuned for virtually any label type and size.

[fabiodalez-dev]

Thanks — you're right, and this is fixed in v0.7.34 (out now).

The layout was fundamentally fixed-size: fonts were derived only from the label width with low caps, the barcode was capped at 44 mm wide / 10 mm tall, and the row heights were hard-coded in millimetres — so a bigger label just grew its margins, exactly as you described.

I replaced the whole renderer with a proportional one:

• Content is laid out as a stack of weighted blocks (the barcode dominates) that together fill the entire label area, centered, for both portrait and landscape.
• Each text line auto-fits: its font starts from the height allocated to that block and only shrinks if needed to fit the width — so text is as large as the label allows and never overflows.
• The barcode fills the width and scales its height with the label.

I verified it visually at 25×38, 70×36, your 89×41, and a large 60×90 — the content now fills each label instead of floating small in the middle — and there's a regression test that measures the actual title glyph height in the generated PDF and requires it to grow with the label.

I also added your second request: a configurable "Inner padding (mm)" field in Settings → Labels, applied on every side on top of the automatic margin, so you can fine-tune the inset for any label stock.

On Docker: the 0.7.34 image is auto-building now and will land on Docker Hub shortly — then docker compose pull && docker compose up -d. The in-app updater (Admin → Updates) already offers it too.

Release: https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.34

[nickun]

Tried to update by the button shows the error on the "Downloading update" stage. Waiting to the docker version published.:

Update failed
Installation failed: Update aborted before any change: the PHP process cannot write to these paths: .coderabbit.yaml, .htaccess, .htaccess.example, .nginx.conf.example, .rsync-filter, .semgrepignore, LICENSE, MOBILE_API_SPEC.md, README.md, STATUS.md, app/Controllers/Admin/CmsAdminController.php, app/Controllers/Admin/LanguagesController.php, app/Controllers/Admin/MessagesController.php, app/Controllers/Admin/NotificationsController.php, app/Controllers/Admin/RecensioniAdminController.php, …. Fix the permissions (ownership/write access for the web-server user) and retry, or run the update from the command line as the file owner: php scripts/manual-upgrade.php

[fabiodalez-dev]

That error is expected on Docker — and it's actually the updater protecting you rather than a bug. On this image the application files are owned by root (baked into the image), while PHP runs as www-data, so the in-app updater can't overwrite them. It checks that up front and aborts before touching anything, which is why you see "aborted before any change" and nothing was left half-updated.

On Docker you don't use the in-app updater at all — you move the container to the new image, which is now published:

docker compose pull && docker compose up -d

Your data lives in the database and in the storage/uploads volumes, so the swap is safe. This pulls fabiodalez/pinakes:0.7.34 (it's on Docker Hub as of a few minutes ago) and brings the container up on the new version — no permission juggling needed.

(The in-app "Updates" button is meant for classic/shared-hosting installs where the web-server user owns the files. I'll make the updater detect a container and point to docker compose pull instead of showing that permission error — thanks for surfacing it.)

[nickun]

Feedback — Email/SMTP Testing and Due Date Visibility

Thank you for fixing the physical copy numbering and label content scaling issues — both now work well.
Two more items to report:

1. No way to verify SMTP/email settings are working
   I've configured SMTP settings that are confirmed valid (tested successfully in other projects), but I have not received any emails from the system, and there's no way to confirm whether the issue is with the settings, the sending logic, or something else.
   Request: Please add a "Send test email" button in the email/SMTP settings, which sends a test message to the configured recipient (or the currently logged-in admin) and clearly reports success or shows the specific sending error. This would make it much easier to diagnose configuration issues.
2. No due date visibility or notifications for loans approaching/at expiration
   As a test, I registered a loan with a due date of today, and found that there is no clear indication anywhere that it is due:

• No notifications are shown regarding the upcoming or current expiration of the loan.
• The "Loans List" page shows the status as "In Progress" but does not include a "Due date" column, making it difficult to identify which loans are close to or past their return date without opening each one individually.
• On the dashboard, the "Active Loans" list does not visually highlight overdue or due-today items in red — this is inconsistent with the "Physical Copies" list in the book details page, which does correctly highlight copies with a due date of today in red.

Request:

• Add a "Due date" column to the "Loans List" page.
• Apply the same red-highlighting logic used in the "Physical Copies" list (for items due today/overdue) to the "Active Loans" list on the dashboard, for consistency.
• If not already present, consider adding a notification mechanism (in-app and/or via the email system referenced above) for loans that are due today or overdue.

[fabiodalez-dev]

All three items from your 07-13 round are in v0.7.37-rc.1 (release candidate), out now.

1. Send test email. Settings → Email has a Send test email button that sends a message with your current config (to a chosen address, or the logged-in admin) and reports the result inline — a green success line, or the specific error. While wiring it I also found and fixed the likely cause of "settings valid but no mail arrives": the smtp driver used a hand-rolled client that never checked the server's replies and reported success even when the message was rejected. Both the smtp and phpmailer drivers now go through PHPMailer, which verifies the handshake/auth/recipient and surfaces the real error — so the test button will tell you the truth.

2. Due-date visibility. The Loans List has a dedicated Due date column, turned red when a loan is due today or overdue. The dashboard's Active Loans list uses the same red highlight — the exact rule the Physical Copies table already used, so it's consistent everywhere. "Today" is computed in the application timezone, not the browser's.

3. Due/overdue notifications. The warning query was matching the due date exactly at today + N days, which silently skipped a loan due today (your exact repro) — widened to BETWEEN today AND today + N, and the in-app notice reads "scade oggi" at zero days. It also goes out as the warning email (so the test button above doubles as a way to confirm those arrive) and as a mobile push.

It's a prerelease, so it isn't the auto-update "latest" yet — download it from the releases page: https://github.com/fabiodalez-dev/Pinakes/releases/tag/v0.7.37-rc.1 . Give it a run and let me know if the due-date and notification behaviour fits your workflow.

[fabiodalez-dev]

v0.7.37 is now the stable release (out of RC) — it's the "latest", so your instance can update straight from Settings → Updates. Everything from the previous round is in it: the Send test email button (with the SMTP driver fix that was the likely cause of "settings valid but no mail arrives"), the Due date column + red due-today/overdue highlighting on both the loans list and the dashboard, and the due-today/overdue notifications. Let me know how it holds up in your workflow.