Clarification on $modx->addPackage()

I’m working through some of the examples in the docs (e.g. http://rtfm.modx.com/display/revolution20/Using+Custom+Database+Tables+in+your+3rd+Party+Components ). So far, I’m able to generate my own XML schema from an existing database, and I’m also able to generate the class and map files.

But I’m confused as to how a Snippet is supposed to use the addPackage method. What’s confusing me is that there’s this whole mess of folder structure that is inferred, but never actually shown.

Let’s say I’ve created XML schema for my_package here:



And I generated classes into my /my_package directory. I used my own definition for the class (my_package), so I end up with this:



Lots of files all over the place, but I think they’re correct. I’m not sure what the exact arguments need to be to the addPackage(). The following doesn’t seem to do anything:



And the man page doesn’t clarify anything: http://rtfm.modx.com//display/xPDO20/xPDO.addPackage

Does the first argument have to match the name of the sub-folder inside my models directory (named "my_project")? In other words, is the second argument a name of a directory containing sub-folders with classes and maps? Or do I have to specify the sub-directory as part of the path argument, e.g. ’/Users/everett/Sites/modx-revo/html/my_package/model/my_project’? And does it or doesn’t it need a trailing slash?

I’ve tried several options, but I can’t seem to get connected with my custom database table.

Thanks for any pointers.

Aha. I figured this out and I’m updating the documentation to make it more clear. Here are my pointers.

1. Before using $modx->addPackage() remember that the $modx object is an instantiation of xPDO. If the database tables you’re trying to access are not inside the MODx database, you’ll need to instantiate a new xPDO object that points to that separate database a la http://rtfm.modx.com/display/xPDO20/Database+Connections+and+xPDO

2. The 1st argument to the addPackage() method should be the name of the folder which contains all of your tablename.class.php files and the mysql sub-folder with the tablename.map.php and tablename.map.inc.php files. Normally, the folder that contains the myriad class and map files lives inside the "model" folder inside your package folder, but strictly speaking, that’s just good housekeeping: addPackage() doesn’t care if you have a messy room, it just wants to know which sub-folder contains the map and class files. It’s not the full path, it’s just the folder name. The path to the parent folder is the 2nd argument.

3. The 2nd argument to the addPackage() method is the full path to the parent folder which contains 1 or many sub-folders which in turn contain the map and class files. Often, this argument makes use of the XPDO_CORE_PATH constant, but that’s just common usage and organizational preference.

4. the getCollection() method expects a class name, not a table name. So if your XML schema file defines your table like this:


then you’d access it via:


So altogether, my Snippet looks like this:

You can also specify the table prefix as third argument.