How to properly take over a complex PHP project

Question

I've been tasked to correct some issues on the backend of a large website project that has been outsourced for some time. The original developers and us are not on good terms so it's not feasible to get them involved.

The technology stack is as follows:

• MySQL 5.x
• PHP 5.3 (and a variety of supporting libraries)
• Apache with mod_rewrite

The problems I am facing are:

• No documentation, not even comments
• 4 index files in root, plus 2 main files in a combo of php and html and 1 default.php, the referenced index file in .htaccess references their local test server.
• Duplicate file names / files
• Atrocious file system layout ( ultiple js folders, multiple script folders etc )
• Reliance on original mysql functions ( not mysqli or PDO )
• multiple frameworks, JQuery, various marketplace API's etc.

It has been a highly frustrating several hours trying to sort out where to begin with this mess, let alone how to fix the items I need.

So my question is: What would be the best place to start or If this was dropped on your lap, how would you approach it?

I know this is subjective, and opinions are what I am looking for, so any advice is appreciated.

Answer 1

1. If it ain't broke, don't fix it. I'm assuming the code has been running functionally for some time, and your business process has assured the previous developers have met the SLA you are now shooting for. Which means, in lack of bugs or new feature requests, you don't have to touch anything ever again. Of course you do but it's important to understand this point first. Your goal is not to rewrite or even to understand a complex project. It's to be able to ascertain enough information on requests you do have to make to fix relevant pieces and touch relevant code only.

2. Strategies for making isolated changes are very different than strategies for understanding or re-architecting whole code bases. If you are asked to make a small change, often the best thing to do is enter your application, probably via an HTTP request in your case, while having your server running under a debugger. Now you can simply watch the logic the code is following and have an idea of the relevant architecture. The debugger is your tour guide through the fog of war.

3. Consider making a small change with some code rot. Often you will be able to say, "I know this code change will work, even though it's probably bad design." This can be a reasonable choice. But of course you do need to establish that you do in fact know the code change will work, so you will have to study relevant pieces some amount. Keep security risk in mind - if you slap something together and it works well on a few test cases, do you understand the system well enough to be wary of disastrous corner cases?

4. Your early steps should include getting your code under source control and learning the moving parts in production. Source control is a big one, obviously, and you want to keep track of changes that you make very well. If you have not been in the habit of making cohesive git commits, this would be a good time to start, because you're likely going to want to be doing things like cherry-pick and subtle rollbacks more than when working on code you know well. Branch intelligently: now in production, changes I've made that I think are safe, changes I've made that are just poking around to see what stuff does but I might want to refer to later anyway.

   But beyond that, think of questions like: do you know your environments? If you run the source from your laptop will it break things in production? Or is there a safe development environment? Also, think of components outside the software and account for them - build system, unit tests, logging, monitoring and error notification, etc. It hurts to make a broken change then discover you also broke the monitoring on it.

5. Be prepared to make the case for an expensive redesign or rearchitecture. As maintenance tasks you have to do on this project get larger in scope or more frequent, and if you really are convinced the code you are working on is poor quality, you will simply have to make the case that replacing it is cheaper in the long run than maintaining it. Find pieces that can be affordably rewritten rather than rewriting the whole thing. This may mean isolating a data layer or logging system, all one component at a time.

   The extreme case is of course to throw out the entire project and rewrite in, say, Ruby from scratch, but if it comes to this, it's probably more because you were not savvy enough than because the code was that awful. You should be able to identify pieces that you understand why are awful and how to turn them into maintainable components and affordably rewrite those with a general sense of the scope of what you are getting into. The worse the code or the less savvy you are, the bigger the piece, but throwing out everything will be a last resort.

Answer 2

I would start by hunting down and fixing the bugs I was tasked to fix. Use bug hunting to get familiar with how the code works. Along the way make mental notes about any glaring problems I might see. Since you're using mysql_ functions, I'd pay special attention to fixing any possible injection problems.

Resist the urge to launch immediately into re-write mode. For starters, you may not have the specific domain knowlege necessary for such a step at this point. Better to at least have a few months with the existing code base before you start evaluating the possibility of a rewrite. It may be, for example, that some of the 'problems' you see in the code end up making more sense to you as you get familiar with it.

Answer 3

I'm going to ignore the possibility of a rewrite, and only address how to attack this particular problem, assuming a rewrite is not in the cards.

First thing to do: spend the time to figure out what it's doing and how, and document it as you go. Then, break it down in to smaller pieces. Instead of being overwhelmed by the massive size of the project, figure out what things you can work on atomically. Some suggestions:

• Abstract out the database calls in to a class (either your own, or PDO, or another library)
• Restructure the assets so they're more logical
• Consolidate the front-end libraries so it's only using one

I'm sure there's a dozen (or a hundred) different areas that need work. Don't think about that; think about the first one to attack.

Answer 4

My preferred approach is:

Set up some basic documentation yourself

• class diagram

• ERD of data

Next debug through some parts of the application to get an overview of the architecture. From that you can construct an abstract view. Again, document it.

By the time you are at this point, you should be more familiar with the project.

Answer 5

I had a similar issue a couple of years ago.

After a lot of research, I found out it would take much less time to build a whole new system than to try to fix the one that was ready. Most important: try to fix that messy code would certainly leave lots of security holes.

As the only think that was truly relevant was the db (which was also a mess), I first planned a db scheme and built a script to migrate the db to fit my scheme and built a new application the right way.

I don't know if you may do something like this but maybe this line of thought may help.

Answer 6

I think that I would approach it one of these ways:

• Talk to the previous developers even if you are on nasty terms

• Talk to somebody that was around when the website was first developed/in development

• Do a complete redesign

• Read through all of the code and make any changes to each line that needs to be changed
  (this will take a long long time though)

• Tell your boss that you are not in a position to do this

• Ask your boss to hire more people to get the job done with you

• Try to find out exactly what each page does before doing anything

That is all that I can think of at the moment, but if I have any other ideas I will edit my answer.