Bug 39488

Summary: Update Koha::Object(s) to allow for polymorphic classing
Product: Koha Reporter: Martin Renvoize (ashimema) <martin.renvoize>
Component: Architecture, internals, and plumbingAssignee: Martin Renvoize (ashimema) <martin.renvoize>
Status: Pushed to main --- QA Contact: Tomás Cohen Arazi (tcohen) <tomascohen>
Severity: enhancement    
Priority: P5 - low CC: dcook, lucas, paul.derscheid, tomascohen
Version: unspecified   
Hardware: All   
OS: All   
GIT URL: Initiative type: ---
Sponsorship status: --- Crowdfunding goal: 0
Patch complexity: Small patch Documentation contact:
Documentation submission: Text to go in the release notes:
Koha's object framework now supports polymorphic classing, allowing different object subclasses to be instantiated based on field values in shared database tables. This enhancement updates `Koha::Object` and `Koha::Objects` classes to pass the original `DBIx::Class` result object to the `object_class` method, enabling dynamic class selection based on record content. This works across all standard retrieval methods including `find`, `find_or_create`, `single`, `next`, `last`, and `as_list`. **Use cases:** - Transport protocols (FTP/SFTP) sharing a common table but requiring protocol-specific methods - Account lines where debits and credits share a table but need type-specific behaviour - Any scenario where related object types share storage but require distinct method implementations **For developers:** To implement polymorphic classes, define a `_polymorphic_class_map` method in your `Koha::Objects` class that returns a hashref mapping field values to class names. The framework will automatically instantiate the appropriate subclass based on the stored data. A template for implementing polymorphic classes is included in the codebase. Test::Builder has also been updated to introspect polymorphic class maps for comprehensive testing.
Version(s) released in:
25.11.00
Circulation function:
Bug Depends on:    
Bug Blocks: 39190    
Attachments: Bug 39488: Add $result to Koha::Objects `object_class` calls
Bug 39488: Add template for required polymorphic class methods
Bug 39488: Use introspection in TestBuilder tests
Bug 39488: Unit tests
Bug 39488: Add $result to Koha::Objects `object_class` calls
Bug 39488: Add template for required polymorphic class methods
Bug 39488: Use introspection in TestBuilder tests
Bug 39488: Unit tests
Bug 39488: Add $result to Koha::Objects `object_class` calls
Bug 39488: Add template for required polymorphic class methods
Bug 39488: Use introspection in TestBuilder tests
Bug 39488: Unit tests

Description Martin Renvoize (ashimema) 2025-03-31 09:22:49 UTC
This splits out the proof of concept code in bug 39190 that allows for polymorphic Koha Object classing.

We update our Koha::Object(s) classes to pass back $result and propose a signature for class selection with resultsets.

This allows for subclassing of an object based on a field in a shared table so one can keep methods grouped for their tasks more easily.

Example use cases are (S)FTP where we want to store the basic transport details in one table and then dynamically load the right set of transport protocol specific methods based on the transport type.  We might also want to update the Account Line classes to work in a similar way, where we store both debits and credits in one table and would want some shared and some specific methods based on the account line type.
Comment 1 Martin Renvoize (ashimema) 2025-03-31 12:15:09 UTC
Created attachment 179985 [details] [review]
Bug 39488: Add $result to Koha::Objects `object_class` calls

This allows us to do dynamic polymorphic classing on calls to 'find',
'find_or_create', 'single', 'next', 'last' and 'as_list' etc.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 2 Martin Renvoize (ashimema) 2025-03-31 12:15:12 UTC
Created attachment 179986 [details] [review]
Bug 39488: Add template for required polymorphic class methods
Comment 3 Martin Renvoize (ashimema) 2025-03-31 12:15:14 UTC
Created attachment 179987 [details] [review]
Bug 39488: Use introspection in TestBuilder tests

We update the testbuilder tests here to look for signs of a polymorphic
class map and use it to test the different class options for this base
class

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 4 Martin Renvoize (ashimema) 2025-03-31 12:36:04 UTC
Hmm, I'm struggling to come up with explicit tests for these changes.  The main change here is that we consistently pass the original DBIx::Class row objects into the object_class meta method so that we can query the content to ascertain which polymorphpihc subclass to use for the subsequent _new_from_dbic calls.
Comment 5 Martin Renvoize (ashimema) 2025-04-01 13:35:57 UTC
Created attachment 180189 [details] [review]
Bug 39488: Unit tests
Comment 6 Martin Renvoize (ashimema) 2025-04-01 13:36:50 UTC
Transferring Kyles SO from the bug this was split out from.
Comment 7 Martin Renvoize (ashimema) 2025-08-01 13:44:49 UTC
Created attachment 185006 [details] [review]
Bug 39488: Add $result to Koha::Objects `object_class` calls

This allows us to do dynamic polymorphic classing on calls to 'find',
'find_or_create', 'single', 'next', 'last' and 'as_list' etc.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 8 Martin Renvoize (ashimema) 2025-08-01 13:44:51 UTC
Created attachment 185007 [details] [review]
Bug 39488: Add template for required polymorphic class methods
Comment 9 Martin Renvoize (ashimema) 2025-08-01 13:44:53 UTC
Created attachment 185008 [details] [review]
Bug 39488: Use introspection in TestBuilder tests

We update the testbuilder tests here to look for signs of a polymorphic
class map and use it to test the different class options for this base
class

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 10 Martin Renvoize (ashimema) 2025-08-01 13:44:56 UTC
Created attachment 185009 [details] [review]
Bug 39488: Unit tests
Comment 11 Tomás Cohen Arazi (tcohen) 2025-08-29 14:23:57 UTC
Created attachment 185931 [details] [review]
Bug 39488: Add $result to Koha::Objects `object_class` calls

This allows us to do dynamic polymorphic classing on calls to 'find',
'find_or_create', 'single', 'next', 'last' and 'as_list' etc.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 12 Tomás Cohen Arazi (tcohen) 2025-08-29 14:24:01 UTC
Created attachment 185932 [details] [review]
Bug 39488: Add template for required polymorphic class methods

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 13 Tomás Cohen Arazi (tcohen) 2025-08-29 14:24:04 UTC
Created attachment 185933 [details] [review]
Bug 39488: Use introspection in TestBuilder tests

We update the testbuilder tests here to look for signs of a polymorphic
class map and use it to test the different class options for this base
class

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 14 Tomás Cohen Arazi (tcohen) 2025-08-29 14:24:07 UTC
Created attachment 185934 [details] [review]
Bug 39488: Unit tests

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 15 Lucas Gass (lukeg) 2025-09-19 19:25:55 UTC
Nice work everyone!

Pushed to main for 25.11
Comment 16 Lucas Gass (lukeg) 2025-09-19 19:26:51 UTC
Can you please add release notes?