Joomla! Documentation™

The "API16" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Description

Custom install method for components

<! removed transcluded page call, red link never existed >

Syntax

install()

Returns

boolean True on success

Defined in

libraries/joomla/installer/adapters/component.php

Importing

jimport( 'joomla.installer.adapters.component' );

Source Body

public function install()
{
        // Get a database connector object
        $db = &$this->parent->getDbo();

        // Get the extension manifest object
        $this->manifest = &$this->parent->getManifest();

        // Set the extensions name
        $name = strtolower(JFilterInput::getInstance()->clean((string)$this->manifest->name, 'cmd'));
        $check=substr($name, 0, 4);
        if ($check="com_") {
        $name = substr($name, 4); }
        $this->set('name', $name);
        $this->set('element', strtolower('com_'.$name));

        // Get the component description
        $this->parent->set('message', JText::_((string)$this->manifest->description));

        // Set the installation target paths
        $this->parent->setPath('extension_site', JPath::clean(JPATH_SITE.DS.'components'.DS.$this->get('element')));
        $this->parent->setPath('extension_administrator', JPath::clean(JPATH_ADMINISTRATOR.DS.'components'.DS.$this->get('element')));
        $this->parent->setPath('extension_root', $this->parent->getPath('extension_administrator')); // copy this as its used as a common base

        // Make sure that we have an admin element
        if ( ! $this->manifest->administration)
        {
                JError::raiseWarning(1, JText::_('Component').' '.JText::_('Install').': '.JText::_('The XML file did not contain an administration element'));
                return false;
        }

        /*
         * If the component site or admin directory already exists, then we will assume that the component is already
         * installed or another component is using that directory.
         */
        if (file_exists($this->parent->getPath('extension_site')) || file_exists($this->parent->getPath('extension_administrator')))
        {
                // look for an update function or update tag
                $updateElement = $this->manifest->update;
                // upgrade manually set
                // update function available
                // update tag detected
                if ($this->parent->getUpgrade() || ($this->parent->manifestClass && method_exists($this->parent->manifestClass,'update')) || $updateElement) {
                        return $this->update(); // transfer control to the update function
                }
                else if (!$this->parent->getOverwrite())
                {
                        // overwrite is set
                        // we didn't have overwrite set, find an update function or find an update tag so lets call it safe
                        if (file_exists($this->parent->getPath('extension_site'))) { // if the site exists say that
                                JError::raiseWarning(1, JText::_('Component').' '.JText::_('Install').': '.JText::_('Another component is already using directory').': "'.$this->parent->getPath('extension_site').'"');
                        }
                        else { // if the admin exists say that
                                JError::raiseWarning(1, JText::_('Component').' '.JText::_('Install').': '.JText::_('Another component is already using directory').': "'.$this->parent->getPath('extension_administrator').'"');
                        }
                        return false;
                }
        }

        // If there is an manifest class file, lets load it; we'll copy it later (don't have dest yet)
        $manifestScript = (string)$this->manifest->scriptfile;
        if ($manifestScript)
        {
                $manifestScriptFile = $this->parent->getPath('source').DS.$manifestScript;
                if (is_file($manifestScriptFile))
                {
                        // load the file
                        include_once $manifestScriptFile;
                }
                // Set the class name
                $classname = $this->get('element').'InstallerScript';
                if (class_exists($classname))
                {
                        // create a new instance
                        $this->parent->manifestClass = new $classname($this);
                        // and set this so we can copy it later
                        $this->set('manifest_script', $manifestScript);
                        // Note: if we don't find the class, don't bother to copy the file
                }
        }

        // run preflight if possible (since we know we're not an update)
        ob_start();
        ob_implicit_flush(false);
        if ($this->parent->manifestClass && method_exists($this->parent->manifestClass,'preflight')) {
                $this->parent->manifestClass->preflight('install', $this);
        }
        $msg = ob_get_contents(); // create msg object; first use here
        ob_end_clean();

        // If the component directory does not exist, lets create it
        $created = false;
        if (!file_exists($this->parent->getPath('extension_site')))
        {
                if (!$created = JFolder::create($this->parent->getPath('extension_site')))
                {
                        JError::raiseWarning(1, JText::_('Component').' '.JText::_('Install').': '.JText::_('FAILED_TO_CREATE_DIRECTORY').': "'.$this->parent->getPath('extension_site').'"');
                        return false;
                }
        }

        /*
         * Since we created the component directory and will want to remove it if we have to roll back
         * the installation, lets add it to the installation step stack
         */
        if ($created) {
                $this->parent->pushStep(array ('type' => 'folder', 'path' => $this->parent->getPath('extension_site')));
        }

        // If the component admin directory does not exist, lets create it
        $created = false;
        if (!file_exists($this->parent->getPath('extension_administrator')))
        {
                if (!$created = JFolder::create($this->parent->getPath('extension_administrator')))
                {
                        JError::raiseWarning(1, JText::_('Component').' '.JText::_('Install').': '.JText::_('FAILED_TO_CREATE_DIRECTORY').': "'.$this->parent->getPath('extension_administrator').'"');
                        // Install failed, rollback any changes
                        $this->parent->abort();
                        return false;
                }
        }

        /*
         * Since we created the component admin directory and we will want to remove it if we have to roll
         * back the installation, lets add it to the installation step stack
         */
        if ($created) {
                $this->parent->pushStep(array ('type' => 'folder', 'path' => $this->parent->getPath('extension_administrator')));
        }

        // Copy site files
        if($this->manifest->files)
        {
                if ($this->parent->parseFiles($this->manifest->files) === false)
                {
                        // Install failed, rollback any changes
                        $this->parent->abort();
                        return false;
                }
        }

        // Copy admin files
        if($this->manifest->administration->files)
        {
                if ($this->parent->parseFiles($this->manifest->administration->files, 1) === false)
                {
                        // Install failed, rollback any changes
                        $this->parent->abort();
                        return false;
                }
        }

        // Parse optional tags
        $this->parent->parseMedia($this->manifest->media);
        $this->parent->parseLanguages($this->manifest->languages);
        $this->parent->parseLanguages($this->manifest->administration->languages, 1);

        // Deprecated install, remove after 1.6
        // If there is an install file, lets copy it.
        $installFile = (string)$this->manifest->installfile;
        if ($installFile)
        {
                // Make sure it hasn't already been copied (this would be an error in the xml install file)
                if (!file_exists($this->parent->getPath('extension_administrator').DS.$installFile) || $this->parent->getOverwrite())
                {
                        $path['src']    = $this->parent->getPath('source').DS.$installFile;
                        $path['dest']   = $this->parent->getPath('extension_administrator').DS.$installFile;
                        if (!$this->parent->copyFiles(array ($path)))
                        {
                                // Install failed, rollback changes
                                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('Could_not_copy_PHP_install_file'));
                                return false;
                        }
                }
                $this->set('install_script', $installFile);
        }

        // Deprecated uninstall, remove after 1.6
        // If there is an uninstall file, lets copy it.
        $uninstallFile = (string)$this->manifest->uninstallfile;
        if ($uninstallFile)
        {
                // Make sure it hasn't already been copied (this would be an error in the xml install file)
                if (!file_exists($this->parent->getPath('extension_administrator').DS.$uninstallFile) || $this->parent->getOverwrite())
                {
                        $path['src'] = $this->parent->getPath('source').DS.$uninstallFile;
                        $path['dest'] = $this->parent->getPath('extension_administrator').DS.$uninstallFile;
                        if (!$this->parent->copyFiles(array ($path)))
                        {
                                // Install failed, rollback changes
                                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('Could_not_copy_PHP_uninstall_file'));
                                return false;
                        }
                }
        }

        // If there is a manifest script, lets copy it.
        if ($this->get('manifest_script'))
        {
                $path['src'] = $this->parent->getPath('source').DS.$this->get('manifest_script');
                $path['dest'] = $this->parent->getPath('extension_administrator').DS.$this->get('manifest_script');

                if (!file_exists($path['dest']) || $this->parent->getOverwrite())
                {
                        if (!$this->parent->copyFiles(array ($path)))
                        {
                                // Install failed, rollback changes
                                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('Could not copy PHP manifest file.'));
                                return false;
                        }
                }
        }

        /*
         * Let's run the install queries for the component
         *      If Joomla 1.5 compatible, with discreet sql files - execute appropriate
         *      file for utf-8 support or non-utf-8 support
         */
        // try for Joomla 1.5 type queries
        // second argument is the utf compatible version attribute
        $utfresult = $this->parent->parseSQLFiles($this->manifest->install->sql);
        if ($utfresult === false)
        {
                // Install failed, rollback changes
                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('SQLERRORORFILE')." ".$db->stderr(true));
                return false;
        }

        /*
         * If we have an install script, lets include it, execute the custom
         * install method, and append the return value from the custom install
         * method to the installation message.
         */
        // start legacy support
        if ($this->get('install_script'))
        {
                if (is_file($this->parent->getPath('extension_administrator').DS.$this->get('install_script')) || $this->parent->getOverwrite())
                {
                        ob_start();
                        ob_implicit_flush(false);
                        require_once $this->parent->getPath('extension_administrator').DS.$this->get('install_script');
                        if (function_exists('com_install'))
                        {
                                if (com_install() === false)
                                {
                                        $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('Custom install routine failure'));
                                        return false;
                                }
                        }
                        $msg .= ob_get_contents(); // append messages
                        ob_end_clean();
                }
        }
        // end legacy support

        // Start Joomla! 1.6
        ob_start();
        ob_implicit_flush(false);
        if ($this->parent->manifestClass && method_exists($this->parent->manifestClass,'install')) {
                $this->parent->manifestClass->install($this);
        }
        $msg .= ob_get_contents(); // append messages
        ob_end_clean();

        // Add an entry to the extension table with a whole heap of defaults
        $row = & JTable::getInstance('extension');
        $row->set('name', $this->get('name'));
        $row->set('type', 'component');
        $row->set('element', $this->get('element'));
        $row->set('folder', ''); // There is no folder for components
        $row->set('enabled', 1);
        $row->set('protected', 0);
        $row->set('access', 0);
        $row->set('client_id', 0);
        $row->set('params', $this->parent->getParams());
        $row->set('manifest_cache', $this->parent->generateManifestCache());
        if (!$row->store())
        {
                // Install failed, roll back changes
                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.$db->stderr(true));
                return false;
        }

        // Time to build the admin menus
        $this->_buildAdminMenus();

        // Clobber any possible pending updates
        $update = &JTable::getInstance('update');
        $uid = $update->find(Array('element'=>$this->get('element'),
                                                        'type'=>'component',
                                                        'client_id'=>'',
                                                        'folder'=>''));
        if ($uid) {
                $update->delete($uid);
        }

        // We will copy the manifest file to its appropriate place.
        if (!$this->parent->copyManifest())
        {
                // Install failed, rollback changes
                $this->parent->abort(JText::_('Component').' '.JText::_('Install').': '.JText::_('COULD_NOT_COPY_SETUP_FILE'));
                return false;
        }

        //TODO: Register the component container just under root in the assets table.

        // And now we run the postflight
        ob_start();
        ob_implicit_flush(false);
        if ($this->parent->manifestClass && method_exists($this->parent->manifestClass,'postflight')) $this->parent->manifestClass->postflight('install', $this);
        $msg .= ob_get_contents(); // append messages
        ob_end_clean();
        if ($msg != '') {
                $this->parent->set('extension_message', $msg);
        }

        return $row->extension_id;
}

<! removed transcluded page call, red link never existed >

Examples

<CodeExamplesForm />