Proper folder structure for custom component

Question

I'm trying to use the joomlatools joomla-console in a new project. However, I can't use the symlink functionality because of my directory structure.

In the past I've always built components with a simple

administrator/
    controllers
    models
    views
    etc
site
    controllers
    models
    views
    etc

structure, and it works fine when you zip / install it.

Joomlatools says you should use

administrator/
  components/
    mycomponent/  
      controllers
      models
      views
      etc
site/
  components/
    mycomponent/
      controllers
      models
      views
      etc

structure.

What do you use and which is "right"?

Answer 1

There is no right or wrong way to structure your code, however there are certainly better ways.

Why

The structure we use at Joomlatools stems from the need to have a standardised developer friendly structure. We don't like to re-invent the wheel so the most logical choice is to use the structure of Joomla.

The symlinker is build for developers who wish to symlink code from a Git repo into a Joomla installation. We use this for all our Joomla component development, it keeps our code in sync, allows us to change branches, while we work directly in the Git repo.

The problem with rsync is that to keep code in sync you need to manually re-sync it each time a change is made as rsync need to copy the changes over. This is less useful when developing.

Benefits

Using this structure gives you following benefits :

• You can use the symlinker that is part of our Joomla Console to easily symlink your code from a local Git repo into a Joomla install allowing you to keep things synced automatically.

• You can work with complex packages. Our Joomlatools extensions include not only a component they also include modules, plugins, libraries etc. All of which need to be part of one package to prevent our users from needing to install everything separately.

   administrator/
        components/
          com_foo/  
            controllers
            models
            views
         modules/
           mod_bar
      site/
        components/
          com_foo/  
            controllers
            models
            views
         modules/
           mod_bar
      plugins/
         foo/
           bar/
  

A great example of this structure you can find in our Joomlatools example Todo component. It follows the Joomla structure and as you can see includes modules, and plugins etc.

Creating your own symlinker

Finally, if you would like to use rsync using the Joomla Console or if you would like to create your own symlinker solution that follow your preferred structure you can consider creating a Console Plugin.

With the release of the 1.3 version of the Console you can now create your own plugins, distribute them using Packagist and install them using $ joomla plugin:install.

Happy coding!

Answer 2

No structure is wrong, the nice thing about Joomla is it does not force you. Your first one in the aspect of it being structured within an install-able archive I would say is the closest to standard. Some developers prefer everything in one directory, others prefer 2-3 well split folders. Some even might have a folder for every file, nothing is incorrect in the end as it all "works". Though personally although I have no experience with joomlatools, if that structure is meant for the install archive it seems rather "excessive", no real reason for 2 of the folder levels.

This next part is not directly related to the question

Also for symlink i don't think it can ever really work, if any file references another file its going to look for it based on the "real" file (so if you have root/installable/file.php going to root/joomla/file.php it assumes you are in root/installable). There may be a way around that but I found a better alternative that does not have as many potential issues, rsync. Of course you need command line but I have this working on a shared host even with limited ssh access.

#!/bin/bash

# sync
rsync -r /home/joomla/components/com_component/administrator/* /home/joomla/public_html/administrator/components/com_component/
rsync -r /home/joomla/components/com_component/site/* /home/joomla/public_html/components/com_component/
rsync -r /home/joomla/components/com_component/administrator/language/* /home/joomla/public_html/administrator/language/

It got a bit to it but you can see that with any folder structure you can map the files to the proper folder, you only need to install it once to get the database records (and again if you change anything). You may also be able to just use CP, but this worked for me so I had no reason to change (and has the ability to work across servers).

Though this needs to be run every time you do an update, but not to hard once you get the hang of it. You can also do it in reverse and instead just edit straight on your dev site for the component (again there may be a way around that, just have not worked on it yet).

Answer 3

It's really all dependent on personal preferences and what you specify in your manifest file.

See Manifest files (where you tell Joomla your file structure in the zip) https://docs.joomla.org/Manifest_files

If you set up your project with an extension specific Phing build file you will set it once and never care again since the zip is built automatically. https://github.com/akeeba/buildfiles/blob/master/phing/README.md

Answer 4

I've just built a relatively complex component on http://component-creator.com and it looks like the correct way is the first one.