Grotworx
Grotworx
This is a lightweight OOP framework for building a website or web application. The framework itself is driven by less than five files. The rest of the files included are utility functions and classes to make the job of the programmer easier.
Directory Structure
The following is the directory structure for Grotworx:
app/
config/
controllers/
data/
images/
models/
printq/
views/
doc/
system/
includes/
libraries/
index.php
The app/ Directory
This directory has placeholder directories for user files. They’re names
in obvious ways. A given user may not need all these, but they don’t
take up much space by default. They could mostly be deleted or renamed
if the user prefers. However, there are two exceptions. The
controllers directory contains the file welcome.php, which is the
default controller. Since this is the default controller, it should not
be removed. However, the user may modify it as desired. Likewise, there
is an index() method within that controller which should not be
removed. But again, it can be modified.
The system/ Directory
This contains a variety of class files and files which contain useful utility functions. The following are critical to the operation of the framework, and should not be removed:
system/libraries/controller.lib.php
system/libraries/router.lib.php
Other files may be of use to the programmer, but may be removed or edited. However, note that upgrades to Grotworx will overwrite any changes to these files and replace any missing files.
system/libraries/controller.lib.php
This is the parent controller from which all user controllers inherit.
It contains a model() method which allows the user to easily
instantiate whatever model they choose (in the models directory). If
needed, it does allow parameters to be passed into the model, such as a
database handle. In addition, this class contains a view() method
which can be called with or without parameters. This includes the view
file (in the views directory) specified.
system/libraries/router.lib.php
This is a router class used by the index.php file to parse and route
the system to the proper controller. See below for a discussion of URLs.
The doc/ Directory
The doc/ directory contains PHPDoc generated documentation of the
individual files and classes comprising Grotworx. These files aren’t
needed in a standard installation. They are for the benefit of
programmers who want to use the included classes. To see this
documentation, surf to
http://example.com/doc/index.html
If you don’t need the files in this directory, or you’ve finished with them, feel free to delete the directory in any live installation.
The index.php File
This is the first page any visits to your site will hit. It sets various constants, pulls in error functions, message functions (to inform users about events, checks for and includes the bootstap file, if any (see later), and then instantiates the router class. The router class parses the URL and directs execution to the proper place.
The app/bootstrap.php File
The index.php file, before it launches the controller, checks for the
existence of an app/bootstrap.php file. If found, it will include()
it. The user can put whatever they like in that file. You can define
constants, include files, instantiate classes, whatever. After this file
is included, the router class is instantiated.
URLs
The basic form for URLs is:
index.php?url=controller/method
Typical URLs will look like this: index.php?url=dogs/poodle. The
server hits the index.php file, and the router class parses the
remainder of the URL. In the above case, the server would expect to see
a file called app/controllers/dogs.php, which would contain a
controller class. The class would extend the parent controller class
(see the “welcome” controller for an example). In that class, it would
expect to see a method called poodle(), which would call in the model
and view.
A URL which looks like this: index.php?url=dogs will route the user to
the same controller. Since the URL doesn’t specify anything after
“dogs”, the router expects a default method called index() to exist in
the controller.
The URL index.php gets the user to the default “welcome” controller
and the default “index” method.
Installation
Just copy or git clone Grotworx to wherever your site will live. Then
populate its app/ directory with your files. The “welcome” controller
and its associated view (app/views/index.view.php) are examples of how
to structure a Grotworx site. Incidentally, when upgrading, the welcome
controller and its view are not overwritten. This allows the user to
customize these without interference. However, be aware that any edits
to the index.php file the user makes will be lost on upgrades, as this
file will be replaced.
Licensing, Credits, etc.
I wrote this to satisfy my own needs. You’re free to use it as you like. If you need a license for it, use the GPL version 2. I’m not responsible for your use of this package or any consequences from its use. If you modify it, I’d like to know about it. I might want to fold in your modifications (and give you credit). If you find bugs, let me know via Gitlab.
Paul M. Foster mailto:paulf@quillandmouse.com
Download at Gitlab