6.0.0-git
2019-11-11

Diff for Doc/Dev/Shares between 5 and 6

+ Horde_Shares

[[toc]]

Some performance charts with the sql driver:

[[image http://chart.apis.google.com/chart?chxl=0:|pdo_sqlite|pdo_pgsql|pdo_mysql|mysqli|mysql&chxp=0,4,3,2,1,0&chxr=0,0,4&chxt=x&chs=440x220&cht=lxy&chco=008000,FF9900,AA0033,3072F3&chd=s:_,NPNpH,_,PPPQH,_,OOQuJ,_,BBBBB&chdl=Share+creation+(Sql)|listShares()+(Sql)|Share+creation+(Sqlng)|listShares()+(Sqlng)&chdlp=b&chls=1|1|1|1&chma=15,15,5,25|0,10&chtt=Horde_Share+performance+(less+is+better)]]

Note: the sqlite driver was test with an in-memory database
----
(wip)
++ How to use horde shares in your custom application ++

//work in progress//

Let's assume you followed the  [CreatingYourFirstModule Creating your first module] guide as far as it applies to horde4 and created a new horde app called "hort". Hort is an old German word for treasure as well as the place where the treasure is kept. Hort should keep safes which hold user/password pairs or other secret credentials. Those safes should be shareable among users. This is where horde_shares comes into play.


+++ basic setup in Application.php _init()

We want to add an injector for the shares API whenever the app is initialized and we want to auto-create an initial "home" share for users which do not yet own one.

<code><code type="php">
    protected function _init()
    {
        // Create a share instance.
        $GLOBALS['hort_shares'] = $GLOBALS['injector']->getInstance('Horde_Core_Factory_Share')->create();

        /* If the user doesn't own a safe, create one. */
        if (!empty($GLOBALS['conf']['share']['auto_create']) &&
            $GLOBALS['registry']->getAuth() &&
            !$GLOBALS['hort_shares']->countShares($GLOBALS['registry']->getAuth())) {
            $identity = $GLOBALS['injector']->getInstance('Horde_Core_Factory_Identity')->create();
            $share = $GLOBALS['hort_shares']->newShare(
                $GLOBALS['registry']->getAuth(),
                strval(new Horde_Support_Randomid()),
                sprintf(_("Default safe of %s"), $identity->getName())
            );
            $GLOBALS['hort_shares']->addShare($share);
        }

    }
</code>

+++ List of safes in Application.php menu()

Next we want to add a page with a list of safes (shares) in the menu. 
Go to the menu() function in Application.php
 
<code><code type="php">
        $menu->add(Horde::url('safes.php'), _("Password Safes"), 'user.png');
</code>


+++ migrations script (database setup) for shares and sharesng driver tables
Create a directory hort/migrations/ with a file 1_hort_tables.php


<code><code type="php">
class HortBaseTables extends Horde_Db_Migration_Base
{
    /**
     * Upgrade.
     */
    public function up()
    {
        $tableList = $this->tables();


        $t = $this->createTable('hort_sharesng', array('primaryKey' => 'share_id'));
        $t->column('share_name', 'string', array('limit' => 255, 'null' => false));
        $t->column('share_owner', 'string', array('limit' => 255));
        $t->column('share_flags', 'integer', array('default' => 0, 'null' => false));
        $t->column('perm_creator_' . Horde_Perms::SHOW, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_creator_' . Horde_Perms::READ, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_creator_' . Horde_Perms::EDIT, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_creator_' . Horde_Perms::DELETE, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_default_' . Horde_Perms::SHOW, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_default_' . Horde_Perms::READ, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_default_' . Horde_Perms::EDIT, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_default_' . Horde_Perms::DELETE, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_guest_' . Horde_Perms::SHOW, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_guest_' . Horde_Perms::READ, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_guest_' . Horde_Perms::EDIT, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_guest_' . Horde_Perms::DELETE, 'boolean', array('default' => false, 'null' => false));
        $t->column('attribute_name', 'string', array('limit' => 255, 'null' => false));
        $t->column('attribute_desc', 'string', array('limit' => 255));
        $t->column('attribute_params', 'text');
        $t->column('share_parents','text');
        $t->end();

        $this->addIndex('hort_sharesng', array('share_name'));
        $this->addIndex('hort_sharesng', array('share_owner'));
        $this->addIndex('hort_sharesng', array('perm_creator_' . Horde_Perms::SHOW));
        $this->addIndex('hort_sharesng', array('perm_creator_' . Horde_Perms::READ));
        $this->addIndex('hort_sharesng', array('perm_creator_' . Horde_Perms::EDIT));
        $this->addIndex('hort_sharesng', array('perm_creator_' . Horde_Perms::DELETE));
        $this->addIndex('hort_sharesng', array('perm_default_' . Horde_Perms::SHOW));
        $this->addIndex('hort_sharesng', array('perm_default_' . Horde_Perms::READ));
        $this->addIndex('hort_sharesng', array('perm_default_' . Horde_Perms::EDIT));
        $this->addIndex('hort_sharesng', array('perm_default_' . Horde_Perms::DELETE));
        $this->addIndex('hort_sharesng', array('perm_guest_' . Horde_Perms::SHOW));
        $this->addIndex('hort_sharesng', array('perm_guest_' . Horde_Perms::READ));
        $this->addIndex('hort_sharesng', array('perm_guest_' . Horde_Perms::EDIT));
        $this->addIndex('hort_sharesng', array('perm_guest_' . Horde_Perms::DELETE));

        $t = $this->createTable('hort_sharesng_groups', array('primaryKey' => false));
        $t->column('share_id', 'integer', array('null' => false));
        $t->column('group_uid', 'string', array('limit' => 255, 'null' => false));
        $t->column('perm_' . Horde_Perms::SHOW, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::READ, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::EDIT, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::DELETE, 'boolean', array('default' => false, 'null' => false));
        $t->end();

        $this->addIndex('hort_sharesng_groups', array('share_id'));
        $this->addIndex('hort_sharesng_groups', array('group_uid'));
        $this->addIndex('hort_sharesng_groups', array('perm_' . Horde_Perms::SHOW));
        $this->addIndex('hort_sharesng_groups', array('perm_' . Horde_Perms::READ));
        $this->addIndex('hort_sharesng_groups', array('perm_' . Horde_Perms::EDIT));
        $this->addIndex('hort_sharesng_groups', array('perm_' . Horde_Perms::DELETE));

        $t = $this->createTable('hort_sharesng_users', array('primaryKey' => false));
        $t->column('share_id', 'integer', array('null' => false));
        $t->column('user_uid', 'string', array('limit' => 255, 'null' => false));
        $t->column('perm_' . Horde_Perms::SHOW, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::READ, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::EDIT, 'boolean', array('default' => false, 'null' => false));
        $t->column('perm_' . Horde_Perms::DELETE, 'boolean', array('default' => false, 'null' => false));
        $t->end();

        $this->addIndex('hort_sharesng_users', array('share_id'));
        $this->addIndex('hort_sharesng_users', array('user_uid'));
        $this->addIndex('hort_sharesng_users', array('perm_' . Horde_Perms::SHOW));
        $this->addIndex('hort_sharesng_users', array('perm_' . Horde_Perms::READ));
        $this->addIndex('hort_sharesng_users', array('perm_' . Horde_Perms::EDIT));
        $this->addIndex('hort_sharesng_users', array('perm_' . Horde_Perms::DELETE));


        if (!in_array('hort_shares', $tableList)) {
            $t = $this->createTable('hort_shares', array('primaryKey' => false));
            $t->column('share_id', 'integer', array('null' => false));
            $t->column('share_name', 'string', array('limit' => 255, 'null' => false));
            $t->column('share_owner', 'string', array('limit' => 255, 'null' => false));
            $t->column('share_flags', 'integer', array('default' => 0, 'null' => false));
            $t->column('perm_creator', 'integer', array('default' => 0, 'null' => false));
            $t->column('perm_default', 'integer', array('default' => 0, 'null' => false));
            $t->column('perm_guest', 'integer', array('default' => 0, 'null' => false));
            $t->column('attribute_name', 'string', array('limit' => 255, 'null' => false));
            $t->column('attribute_desc', 'string', array('limit' => 255));
            $t->primaryKey(array('share_id'));
            $t->end();

            $this->addIndex('hort_shares', array('share_name'));
            $this->addIndex('hort_shares', array('share_owner'));
            $this->addIndex('hort_shares', array('perm_creator'));
            $this->addIndex('hort_shares', array('perm_default'));
            $this->addIndex('hort_shares', array('perm_guest'));
        }

        if (!in_array('hort_shares_groups', $tableList)) {
            $t = $this->createTable('hort_shares_groups');
            $t->column('share_id', 'integer', array('null' => false));
            $t->column('group_uid', 'string', array('limit' => 255, 'null' => false));
            $t->column('perm', 'integer', array('null' => false));
            $t->end();

            $this->addIndex('hort_shares_groups', array('share_id'));
            $this->addIndex('hort_shares_groups', array('group_uid'));
            $this->addIndex('hort_shares_groups', 'perm');
        }

        if (!in_array('hort_shares_users', $tableList)) {
            $t = $this->createTable('hort_shares_users');
            $t->column('share_id', 'integer', array('null' => false));
            $t->column('user_uid', 'string', array('limit' => 255, 'null' => false));
            $t->column('perm', 'integer', array('null' => false));
            $t->end();

            $this->addIndex('hort_shares_users', array('share_id'));
            $this->addIndex('hort_shares_users', array('user_uid'));
            $this->addIndex('hort_shares_users', array('perm'));
        }

    }

    /**
     * Downgrade
     *
     */
    public function down()
    {
        $this->dropTable('hort_shares');
        $this->dropTable('hort_shares_groups');
        $this->dropTable('hort_shares_users');
        $this->dropTable('hort_sharesng');
        $this->dropTable('hort_sharesng_groups');
        $this->dropTable('hort_sharesng_users');
    }

}

</code>