Planning / design document?

[eluser]jabbett[/eluser]
I'm trying to take a fairly complex, enterprise PHP application and rearchitect it to use a development framework. So far, Code Igniter seems to provide the best balance of structure and flexibility, especially important for our group considering that most of our application's data is stored as XML and drawn from a web service (not just pulled from a database as many PHP frameworks assume/require).

I'd like to give my project a fighting chance, so I'm curious if anyone out there can suggest methodologies for planning a Code Igniter-enabled application; I guess it's mostly how to map out necessary models, views, and controllers, but maybe also how to identify the kinds of libraries to integrate, etc. If someone can post a successful design document, or point to any existing examples online, that would be ideal.

[eluser]Michael Wales[/eluser]
I take 37signals stance on design documents - unnecessary. There's really no need to go about planning out every little detail - it's bound to change and in the long run, you're just wasting time. How many times have you written out a design document for a site, referred to it consistently during development, and the end result turned out like the design document stated - rarely I'd bet.

Now, since you are taking a current application and porting it over to run on the CI framework - I'd say a good bit of planning is of course due. I would do a quick look through the current application (and if it's already developed with MVC in mind - this makes it a lot easier) but look at the various functional components of the application - those are your controllers. What kind of data are you working with and how it that data defined - there are your models. Now, what pages are you going to need to get this done - there are your views.

[eluser]jbowman[/eluser]
I've found that 0 planning causes lots of problems, you get halfway through your code writing, and realize you're doing it all wrong.

I've also found that coming up with detailed design documents causes problems, because you get halfway through your code writing, have an epiphany, and realize you're doing it all wrong.

So... I've been going with mindmaps. Using the MVC concept makes it easier. I generally follow the method of

Start with figuring out what information you are going to want to keep, and how you're going to want to insert it and retrieve it. This mindmap works well for your models and database.

Then figure out how the project will be presented to the user. Not the full scale design, but the functional one. This covers your controllers and views.

Then go back and make sure both mindmaps compliment each other, and you really flush out your controllers.

Finally, create mockups for your design, to finish flushing out the views.

At this point, you're ready to dive and start seriously writing code to complete the project. You don't have a step by step design document, you have a few roadmaps and mockups that provide an excellent structure to not only build off of, but keep track of your progress.

Oh and one last caveat... different strokes for different folks, especially for development strategies. This could work for you, this could be incredibly annoying and frustrating.

[eluser]Phil Sturgeon[/eluser]
My order is normally:

1.) Plan your databases.
2.) Make basic models for all tables (get, getList, insert, update, delete)
3.) Work out what all your pages need to be. I want... an arcade. so needs a browsing list, view game page, vote and submit new page. So you controller is arcade.php and methods are browse(), view(), vote() and submit_new()
4.) Work out extra database queries. Need ordered lists, counter updates, etc.
5.) With that done, develop. Output all data in print_r while you work on it.
6.) When all pages show what they should, make some BASIC web 0.1 view files, check it all works and ship it off to some designer-monkey to do the hard parts.
7.) Job done, grab a cold beer.

[eluser]Michael Wales[/eluser]
Pyro - I love your thinking. I do a lot of the same stuff, but unfortunately I skip a few steps in there. When I get home I'm printing that list out and tacking it to my wall - thanks!

[eluser]Crafter[/eluser]
Call me the academic type, but I feel there is always room for good Strong design prior to starting a project.

I'd not suggest using thepyromaniac's database approach to designing applications. Databases are a tool for programmers to store information. While ultimately the database should reflect the users information needs, there is no one-to-one mapping.

This type of approach is useful for "flat-file" data storage - you known where there is a single table for products, no lookup tables and all fields set to strings.

jbowman on the other hands is singing my tune. Your application is written for the user in mind, and therefore should be user-centric. A good approach would start with the identification of what businesss entities or objects the user wishes to manage:

For example, the user might say : "I wish for my application to allow my customers to purchase products that I sell". You might determine that your business entities are 'customer' and product.

These objects/entities then form your controllers. This is because you implement your business rules on your objects. The controllers in the MVC approach controls business logic.

The next step would be be determine the interfaces to your business objects entities, If you consider the product entity, we may have the following interfaces:
search - customer
add_stock - internal
purchase - customer
delete_stock - internal
print_report - internal
order - customer

These interfaces become your controller methods, and the "internal/customer" info tells you how your controller will provide access control (public web or admin utility). The login of each interface should be described in further detail.

Of course, your database design is very important, and each business object should be described as a data entity.

If you do this then your user documentation is well underway!

I use this approach often for my projects. I find that it explains the documents so that my clients will understand, and it simultaneously provides me my design elements. I also use it as a checklist to determine progress on my projects.

Good luck with your project.

[eluser]esra[/eluser]
[quote author="jabbett" date="1186602409"]I'm trying to take a fairly complex, enterprise PHP application and rearchitect it to use a development framework. So far, Code Igniter seems to provide the best balance of structure and flexibility, especially important for our group considering that most of our application's data is stored as XML and drawn from a web service (not just pulled from a database as many PHP frameworks assume/require).[/quote]

CodeIgniter appeals to multiple user audiences with varying levels of expertise. A quick check of the questions on the forums and the content of some threads will reveal this to be true. Some users view CI as a a good solution for migrating from procedural programming to using a framework. More advanced users probably view CI as a basic framework where they can add libraries of their choice to develop applications more suited to their particular needs and the needs and wants of their user audiences.

In your case, you already have an enterprise level application or suite of applications to migrate to CI. You should already know that your user audience or user audiences (which is more often the case for the enterprise) is of paramount importance so enough of that. You should already know how to design user interfaces which can be adapted to your different audiences. You already know how to design database schemas.

Given the above, your major concern is probably maximizing code reuse among your application suite. Most users here tend to use the conventional MVC approach of storing files in the CI recommended directory hierarchy. This can get very messy for an enterprise solution. A smaller group of users follow a modular separation approach patterned after the solutions developed by Zawk or Elliot Haughn. The latter use a CMF-like-framework approach to divide application modules into discrete installables which can be installed, uninstalled and updated independently. For larger applications where one needs to mix and match application modules to meet continuously changing needs, modular separation is probably the better approach to follow for an enterprise project.

There are going to be a basic set of core modules for your applications. For most applications, your going to need to have a configuration editor, user interfaces for installing/uninstalling/upgrading modules and other objects, mail services, internationalization and localization services, etc. You should probably build the basic foundation of modules to use among multiple applications first, then design application-specific modules.

Personally, I use a highly modified version of Zawk's modular separation approach which is considerably different from the conventional MVC approach of storing controller files in a controllers directory, models in a models directory, etc. All files associated with a specific module are stored in a dedicated directory structure for the module. Installing new modules or uninstalling modules in merely a matter of adding or removing module directories from your application. Updating modules and managing module dependencies from your admin user interface is also easier when a modular approach is used. I also store templates and blocks independently in their own directory structures. It's fairly easy to remove the controller, models, and views directories from the CI directory structure if you decided to follow the modular separation approach.

Another advantage of using modular separation is the ease at which you can quickly shell out a directory structure for your application(s).

[quote author="jabbett" date="1186602409"]I'd like to give my project a fighting chance, so I'm curious if anyone out there can suggest methodologies for planning a Code Igniter-enabled application; I guess it's mostly how to map out necessary models, views, and controllers, but maybe also how to identify the kinds of libraries to integrate, etc. If someone can post a successful design document, or point to any existing examples online, that would be ideal. [/quote]

I have yet to see a published design document of any substance, although I'm sure that they exist within commerical and open source projects based on CI. Most of the examples posted so far or no where near the quality or complexity of an enterprise suite of applications. You might find these helpful to learn the basics, then go from there.

CodeIgniter provides a nice foundation to build upon. Once you become acquainted with the basics, it's fairly easy to expand upon and replace the basic family of libraries that CI provides. Unlike some frameworks, this gets very intuitive after a short learning curve (probably a few weeks in your case).

You can use standard UML design tools, some of which are available in open source form and database design tools (e.g., FabForce's DBDesigner is a good open source solution for mysql with characteristics similar to Rational Rose).

http://fabforce.net/dbdesigner4/

If you require more advanced unit testing than what CI provides, SimpleTest is a good replacement.

[eluser]Phil Sturgeon[/eluser]

I’d not suggest using thepyromaniac’s database approach to designing applications. Databases are a tool for programmers to store information. While ultimately the database should reflect the users information needs, there is no one-to-one mapping.

This type of approach is useful for “flat-file” data storage - you known where there is a single table for products, no lookup tables and all fields set to strings

Say what now? "Plan your databases" is open to interperatation i'll give you that, but I mentioned nothing of badly built "flat-files". Any decent programmer will know to go through the stages of normalisation and develop their DB architecture using Visio, MySQL Workbench, etc. I just see no point in teaching grandmothers to suck eggs as im sure he already knows how to make a DB if he is talking about making enterprise level applications :p