PHP API

Read the Framework internals guide to get the absolute most out of this tutorial. We build on concepts that are covered in that guide.

• Documents
  • Create document
  • Edit document
  • Delete document
  • Fetch documents
  • Find the documents for a specific file
• Categories
  • Create category
  • Fetch categories
• A complete script

DOCman comes with a built-in PHP API. Here you can find our tutorials and code samples for the API:

Documents

Create document

You can create a new document by calling the add method of the document controller with document details.

You can find a complete list of document fields in our JSON API documentation.

<?php
$document_details = array(
    'title'              => 'document title',
    'docman_category_id' => 1,
    'storage_path'       => 'path/to/the/file.txt' // part of the path that comes after joomlatools-files/docman-files/
);
$result = KObjectManager::getInstance()
    ->getObject('com://site/docman.controller.document')
    ->add($document_details);

Edit document

Editing a document is done by passing the ID of the document to the controller and then calling the edit action:

<?php
$document_id      = 12345; // document ID
$document_details = array(
    'title'        => 'new title',
    'storage_path' => 'new/path/to/the/file.txt' // part of the path that comes after joomlatools-files/docman-files/
);
$result = KObjectManager::getInstance()
    ->getObject('com://site/docman.controller.document')
    ->id($document_id)
    ->edit($document_details);

Delete document

Deleting is done by passing the ID of the document to the controller and then calling the delete action:

<?php
$document_id = 12345; // document ID
$result  = KObjectManager::getInstance()
    ->getObject('com://site/docman.controller.document')
    ->id($document_id)
    ->delete();

Fetch documents

For fetching documents, we set permission values for the current user, limit the results to 50 documents, and optionally filter by category as well:

<?php
// Get the controller
$controller = KObjectManager::getInstance()->getObject('com://site/docman.controller.document');
$user       = KObjectManager::getInstance()->getObject('user');
// Fetch documents in a category
$documents_in_a_category = $controller
    ->access($user->getRoles()) // Permissions
    ->current_user($user->getId())
    ->enabled(1)
    ->status('published') 
    ->category(1) // Category ID here
    ->limit(50)   // Limiting to 50 documents
    ->offset(0)   // You can set this to 50 in the next call to paginate results
    ->browse();
foreach ($documents_in_a_category as $document){
    var_dump($document->title);
}

Find the documents for a specific file

Here we set permission values for the current user, filter by storage path of the document, and then call the browse event:

<?php
// Get the controller
$controller = KObjectManager::getInstance()->getObject('com://site/docman.controller.document');
$user       = KObjectManager::getInstance()->getObject('user');
// Fetch documents in a category
$documents_for_a_file = $controller
    ->access($user->getRoles()) // Permissions
    ->current_user($user->getId())
    ->enabled(1)
    ->status('published') 
    ->storage_path('path/to/file') // Enter the file path here
    ->browse();
foreach ($documents_for_a_file as $document){
    var_dump($document->title);
}

Categories

Create category

You can create a new category by calling the add method of the category controller:

<?php
$category_details = array(
    'title' => 'category title'
);
$result = KObjectManager::getInstance()
    ->getObject('com://site/docman.controller.category')
    ->add($category_details);

Fetch categories

For fetching categories, we set permission values for the current user, limit the results to 50 categories, and call the browse event.

<?php
// Get the controller
$controller = KObjectManager::getInstance()->getObject('com://site/docman.controller.category');
$user       = KObjectManager::getInstance()->getObject('user');
// Fetch all categories
$categories = $controller
    ->access($user->getRoles()) // Permissions
    ->current_user($user->getId())
    ->enabled(1) 
    ->limit(50)   // Limiting to 50 categories
    ->offset(0)   // You can set this to 50 in the next call to paginate results
    ->browse();
foreach ($categories as $category){
    var_dump($category->title);
}

A complete script

Below script boots Joomla and Joomlatools framework, and then runs your custom code. Save its contents into a PHP file and run it from the browser or the command line:

<?php
define('_JEXEC', 1);
define('JPATH_BASE', __DIR__ . '/administrator');
if (file_exists(JPATH_BASE . '/includes/defines.php')) {
    include_once JPATH_BASE . '/includes/defines.php';
}
require_once JPATH_BASE . '/includes/framework.php';
// Instantiate the application.
$app = JFactory::getApplication('administrator');
// Make sure that a user with add permissions is logged in.
$app->login(array(
    'username' => 'admin', // Change the username here
    'password' => 'admin'  // Change the password here
));
// Boot Joomlatools Framework
JPluginHelper::importPlugin('system', 'joomlatools');
$document_data = array(
    'title'              => 'title', // The document title.
    'docman_category_id' => 1,       // The category ID.
    'storage_path'       => 'path/to/the/file.txt' // part of the path that comes after joomlatools-files/docman-files/
);
$result  = KObjectManager::getInstance()
    ->getObject('com://admin/docman.controller.document')
    ->add($document_data);