Okay, I'm fed up with phpDocumentator. It consumes way much more memory (1.4 GB) and time (5 minutes on 2.6GHz Core 2 Duo) than I'm willing to give it. Does there exist some really compatible program to generate documentation for PHP code?
I've tried PHPDoctor, which looks nice, but it has some missing features. However it is probably closest to be replacement from all solutions I've tried so far.
I've also tried PhpDocGen, but it just bails out with some Perl errors, which I'm too lazy to study.
Doxygen also does not seem to play well with our sources.
PS: The documentation would be for phpMyAdmin, a little bit outdated documentation is here.
Update: The code contains lot of functions and not only objects, what is the biggest problem with Doxygen, because it fails to organize them.
We switched from phpDocumentor to Doxygen because the former did not support PHP 5.3 features like namespaces and closures. phpDocumentor's last update was in 2008.
The major #-attributes are the same in Doxygen, because they both do JavaDoc-style comments. It is quite configurable, too.
You can also try DocBlox; it is a new kid on the block (pun intended) but already supports many of the features that phpDocumentor provides and many of the newer things (like namespaces).
Please try it out at https://www.github.com/mvriel/Docblox
Doxygen is pretty complex, and it's supposed to support PHP 5.3 features. However, it didn't work exactly how I wanted it and I realized it's a big program, but not designed for PHP; so I needed something lighter, simpler and preferably PHP exclusive, because let's face it, PHP does not have quite the common programming language syntax and look.
I know you mentioned it, but I chose PHPDoctor in the end. It does indeed lack some features, but it's simple and fast, exactly what I was looking for.
Let us know what you chose and what were the reasons.
Also something to mention is that I found the PHPDoctor interface to be quite simple and easy to style (with few CSS changes). I was able to create quite a clean page for my docs.
I've been using Natural Docs, works well for me
Related
I am tasked with learning PHP, but there are many things I don't understand. For example, the concept of "variable functions" is not one I've seen anywhere else. There are many other examples, but for brevity, I found PHPWTF, which has many examples of PHP's idiosyncrasies.
Most other languages I've used have either a formal specification (e.g., Haskell 2010) or at least a research paper on their formal semantics (e.g., this for Javascript). However, I can't find anything comparable for PHP.
There is an official "language reference". However, it is very informal, reads like a wiki, and is missing entire sections (e.g., the section on syntax doesn't define the syntax at all). Confirming what I suspected, this guy tells me that there is no official specification, nor even a defined syntax.
Wikipedia has an article on "PHP syntax and semantics", but it only touches on the syntax, and barely mentions semantics.
One paper I've found on PHP is this paper on its assignment semantics. This is a very small fragment of the language and probably not much use to me without some context. There is also this paper on 'SaferPHP', which presumably has to work with some definition of PHP, though I couldn't see any.
Interpreters/compilers provide a semantics, so I thought to look at these. However, the Zend source is intimidating (though it does provide useful test cases), and HipHop runs to 2.7 million LoC. (I find it amazing that people have poured enormous effort into writing compilers for a language without ever writing something like a specification.)
I thought of looking at type systems for PHP for guidance, much like TypeScript provides some guidance for JavaScript. I found these tantalising slides on Hack, an optional type system for PHP. However, it's just slides, and the project seems to be an internal one at Facebook at this time.
Does anyone know of anything better than these poor man's semantics? Or does everyone just "learn by example"?
It seems that you're not after an official standard (which might be useful, for example, to someone writing an independent conforming implementation), but for a presentation of the language that will allow you to make coherent sense of it. Unfortunately there cannot be such a thing, because PHP does not have a coherent formal model behind it. It has grown organically and is now saddled with inconsistencies, most notoriously in function and method naming but also in little details like what counts as true and false, and other similarly worrisome details.
The best one can do to approach PHP, in my opinion, is to get a good feel for the core features and libraries, for the "gotcha's" that you need to watch out for, and (in order to read existing code without distraction) for the anti-patterns that are all too common in real-world PHP scripts. My guess is that it's best to learn PHP under the tutelage of people who know how to work with it effectively, but I didn't have that luxury. (Regarding the documentation: It took me forever before I noticed that you can use square brackets to index into strings. The feature may be mentioned somewhere in the documentation, but not, back then at least, anyplace where it belongs.)
This article gives a nice tour of the kind of things that make a semantic model of the kind you want impossible. (You may want to skip the opening rant and go straight to the discussion of PHP features.) There are many, many other similar texts. Quote: "PHP was originally designed explicitly for non-programmers (and, reading between the lines, non-programs); it has not well escaped its roots."
Don't get me wrong: I work with PHP, and although it's not my favorite language, I wouldn't say I hate it. I would say that to work effectively with it, one must be aware of its nature and limitations. If you're coming to this from Haskell, you're in for quite a shock.
This answer comes a bit after your initial question, but now we finally have a formal semantics for PHP. Check it out: http://www.phpsemantics.org. A paper about it has been recently published in the ECOOP 2014 proceedings, if you are interested you can find the link in the webpage I linked. Regards.
Doesn't directly address your inquiry, but explains some of the magic behind PHP variables.
http://webandphp.com/how-php-manages-variables
Interesting question. I'd regard the manual as the official language reference; I appreciate it isn't quite "formal reference" in the sense you are seeking, but I don't know how much such a thing would be widely desired as something to learn from.
I'm not familiar with PHPWTF, but I'd guess it is in the same mould as the blog post Fractal Of Bad Design (linked by #alexis earlier). I can't peer into the mind of either author, but it seems to me that they are written from the perspective of wanting PHP to be bad. Religious wars frequently dominate on the internet and in programming — the browser you prefer, the IDE/editor you use, your operating system and your choice of framework have all had the same ferocious, partisan and unyielding treatment. Programming languages are, sadly, no different.
It is certainly true that PHP does have a number of design inconsistencies, in particular about how nulls are treated, and in the ordering of parameters in standard functions. However, it is also true that PHP has been hugely successful, despite all that. It spent a long time in the reliability doldrums in 5.0 and 5.1, 5.2 was stable but arguably not enterprise, and it's finally coming of age in 5.3 onwards.
Whilst this might be my biases emerging, I sense a consensus amongst users I read on Stack Overflow that all of the popular languages have their place. This is partly a response to the reality that the ones we dislike won't go away, and partly perhaps that learning .net, Java, Perl, Ruby, PHP, Python etc is pretty much always a good thing. Maybe we have also collectively tired of the flame-wars over each (Java is bloated, PHP is inconsistent, Microsoft is vendor lock-in, Rails is unstable, and so forth).
I've veered rather off-topic, but I tend to regard this particular viewpoint as worth reading, especially for those who would be traditionally minded to disagree with it in relation to PHP.
To address the purpose of your question, how should you learn? Well, learning by example is an excellent approach - one just needs to know which examples to learn. Searching for "PHP tutorial" and "PHP beginner" will — perhaps as is the case with any language — offer a mix of excellent and dreadful material. One might argue that PHP's low barriers to entry have given rise to a large stock of insecure and badly written "how to" articles, and I've certainly seen quite a few!
I think the solution is to look directly at code from well-engineered projects, and to learn from there. Such as:
Symfony2 (and Components)
Zend Framework
Guzzle
Propel
Doctrine
Ah, nearly forgot; this website is also a good place to start.
Post Script: they may be referred to by a different name in other languages, but I expect they all have variable functions. In JavaScript for example, it's object[myFunc]();, where myFunc is a string.
It's not exactly a formal semantics, but, after all these years, the HHVM project has produced a PHP specification!
I'm a PHP developer. I like PHP! It is a really good language if you know how to use it, but I know it allows very bad design sometimes.
It reminds me of JavaScript which has good parts and bad parts. One particular project, CoffeeScript, tries to focus only on the good parts, forcing you to write good code.
I was thinking if something similar could be done with PHP... A new syntax that would be compiled only to good PHP code taking advatage of all the new and exciting stuff we can get with PHP 5.3.
So, getting ahead of some people, I'll ask: Why create a new language on top of PHP if you can just use Ruby or Python or something else?
PHP is easy to deploy anywhere
The language itself has a lot of good features and ideas
There are lots of good libraries written in PHP
...
So, my real questions here are...
Is this a stupid idea? Why would it be? Do you think CoffeeScript is stupid?
How do someone starts to create a new language on top of another? I know nothing about this, but I would like to learn. Where to start?
The idea is definitely not stupid, especially if executed well.
I like coffeescript a lot, but it has it's approach has downsides as well. Debugging a coffeescript script still requires you read the generated Javascript code, which can be tedious, since you haven't written it actually yourself.
I've understood that Jeremy Ashkenas, the creator of coffeescript has started to work on coffeescript after reading "Create your own freaking awesome programming language" by Marc-André Cournoyer.
Good luck!
The reason CoffeScript is a good idea is that if developers want to run code in a client browser they have to use javascript; so the only way to program in a different language is to allow that language to be convertible to javascript.
I'm not sure the same really applies to server side programming. If you've got issues with PHP and want to use a new language there is no real advantage to having that language generate PHP.
On the other hand, a language that was very similar to PHP, but fixed some of the flaws would be a great idea.
Heh, great idea. My thoughts, some contradictory...
There are precedents for civilizing bad languages by putting syntax preprocessors in front of them.
In the early days of Unix, Fortran was popular and about the only portable language because most machines had no C compiler. But the vanilla Fortran of the day didn't even have block structured if-then-else, just a goofy single-statement if or an if-goto. So, the Ratfor language was implemented as a preprocessor for Fortran-66.
I believe there were (are?) Cobol preprocessors that presumably dealt with the verbosity and limitations of early Cobol dialects.
To this day Unix-derived systems ship with a macro processor called m4.
Several CSS preprocessors are available today, most notably Sass and LESS.
But...
Just let it die, and the sooner the better
The problem isn't really in the syntax.
I don't see much of a JavaScript-PHP parallel. JavaScript is a great language. It's kind of the opposite of PHP.
I'm not sure why you say that PHP is a great language. It's one of the worst. Every decent feature is a patch or repatch in a recent version.
As you noted, there is a fixed-up version of PHP already: it's called Ruby and, as a language, it's near-perfect. There is another fixed-up version called Python. The world would be better off in the long run if we support the better systems.
It is here now. A new language which is to PHP what CoffeeScript is to Javascript. (I.e., awesome.)
SNOWSCRIPT
Snowscript code looks like this:
fn how_big_is_it(number)
if number < 100
<- "small"
else
<- "big"
PHP output looks like this:
function how_big_is_it($number) {
if ($number < 100) {
return "small";
} else {
return "big";
}
}
All it needs now, is you.
If it would be to PHP what something like sass is to CSS, I'd be interested. But what would exactly would you want to add? Or would you just want to weed out the bad?
And what would you consider to be the bad?
Writing a PHP syntax transformer would probably be a neat project.
However, don't forget that PHP's standard library is a huge mess. Cleaning that up, would be a far bigger task.
The more I am thinking about this, the more irrealistic it sounds. The reason is simple: There actually are such language proprocessors already. Two of them (though not using PHP as implementation, only as compilation target) can be found here. But simply nobody uses them.
Yes, if the compiler itself were written in PHP, probably more people would use it. But I really can't see a way how to get this popular enough to be worth the work.
Another big problem is, that people mostly are used to their awesome code-highlighting, code-completing, code-inspecting IDE. Without getting IDE support probably merely anybody will use it (and IDE support can only be obtained by having many people use it...)
Thoughts?
I can see writing compilers to JavaScript (because the web imposes it upon us), but this sounds like a waste of time.
Haxe already does this, although it's not specifically targeted at PHP (linked to the Wikipedia article instead of their website because I'm afraid I'm going to get exploited if I visit the real site...)
PHP is easy to deploy anywhere
...as are its vulnerabilities.
I know it allows very bad design sometimes.
That's a bit of an understatement, it doesn't even have a module system, has no encapsulation, and has tons of silly things such as dynamic name resolution.
PHP is slow enough as it is, do you really want something an order of a magnitude slower?
Java is much more easy to deploy anyways, and lets you drop down to the bytecode level if you want. Java also gives you access to moderately sane libraries.
This is something I have thought about already often. PHP just is messy at some points.
Actually, I already have a project PrePHP focusing on providing PHP 5.3 functionality to PHP 5.2. But it adds some minor language features, like func()[0]. I haven't developed this project for some time and it definitely isn't "clean", but it shows, that what you want is possible and actually even not that complicated.
If you are serious about this, I am perfectly willing to collaborate with you.
Very interesting idea and if it come to life i think that i wan't to be involved in :)
For start You may check and read this position http://www.amazon.com/Masterminds-Programming-Conversations-Creators-Languages/dp/0596515170 (iam reading it now). It makes clear how really complicated is to maintain own language.
I agree that PHP definitely could do with some improvement, right now it allows for too much fooling around.
Some things I'd like to see
Static Typing
Required indentation
Proper use of objects (using arrays as objects is just stupid)
Then again, maybe I should just drop PHP and start working with Ruby or Python.
I'm like 8 years too late, but I'll answer anyways for anyone else who stumbles upon this.
Hack is a language developed by Facebook to deal with some of the issues of PHP, since Facebook had a large PHP codebase. Hack adds some nice features on top of PHP such as gradual typing (what TypeScript has) and generics, among other features, and gets rid of some of the more dangerous PHP features. Hack was at one point a superset of PHP, but is no longer completely compatible after removing some of the worse PHP features.
This is slightly different from what you were asking, since at this point Hack has its own interpreter, written by Facebook, but this started out as "better language that compiles to PHP", so I thought it was worth mentioning here.
Is anyone using a HAML implementation for PHP like phpHaml or pHAML? Both projects have seen no activity for about 2 years, and both are < 1.0. Is it feasible/wise to use HAML for a large PHP application, or is it too immature?
Does anybody have experience with Chaml for CakePHP? I played around with it, and it seems to be really picky about whitespace, which I think might cause a few hiccups in a large project with many developers.
I really want to use HAML or something minimalistic like it, but I don't want it to add another layer of debugging problems. Recommendations are welcome.
Oh well, so in the meantime, I did start writing a small site using Chaml, which uses the phpHaml parser. First of all: HAML is so much fun! X-D
Second: phpHaml is still a little buggy. I've had instances where a line like
= $html->link('Something', '/somewhere')
yielded
<?php echo $html->link('Something', '/somewhere'); ?><?php echo $html->link('Something', '/somewhere'); ?>
if the following line was left blank. Inserting something on the following line removed the duplicate. This means you're always required to double check you're actually producing the markup you think you are.
The Chaml plugin is working quite well, I haven't had any particular problems with it. The included SASS parser is not really worth talking about though, it's experimental at best.
Overall, HAML on PHP at this stage does add a slight debugging overhead, so I wouldn't recommend using it to just anybody. It may be worth it if you'd have to type loads and loads of markup otherwise.
I'm currently trying to decide whether diving into the phpHaml parser or switching to Rails is the better decision. ;)
My expertise is not with HAML but with CakePHP so I can only answer part of your question. CakePHP is a tightly coupled framework so you either work with it or against it. If you wanted to use a different template engine such as HAML you'd be better with a loosely coupled framework such as Code Igniter or Zend.
For more information see this thread on using Smarty in Code Igniter or Zend - the same principle would apply for using HAML.
See: http://haml-to-php.com/related%20work.html. It depends on how much of the HAML features you want to use. Most of them get simple HAML right. But if you also want have quoting and maybe advanced features such as %div{:attr=>"foo_#{ php code }"} all but HAML-TO-PHP fail to my knowledge
Aside from the PEAR repository, which I find often has quite messy code with a lot of it using old or deprecated methods and techniques, I was wondering if there was a great place to find simple (and not so simple) PHP examples of some generic functions and good pieces that people have written.
A good example would be the PEAR spreadsheet module I used a while back. The thing worked but it was written quite messily and if I remember correctly, in PHP 4.
I'd like to find something with well written and well documented code that I can refer to and see exactly how people are doing things and why they are doing things that way.
The PHP manual's as good a place to start as any, I've particularly found some of the comments on there helpful.
There's also The PHP Resource Index, which is mostly a jumping off point to other projects' websites.
Don't forget to look at questions tagged PHP on stackoverflow.
Have a look at PHP Classes. They have a large selection of classes, all with user ratings.
There's also Zend Framework spesific ZF Snippets site
Github is another good resource, more often than not it is polished code that is updated frequently.
Getting classes from other people is all well and good but keep upgrade-ability in mind, if i'm using someone else's class and need to tweek it i always extend from it.
Why are so many people still writing crappy versions of things in standard libraries? Not to go after PHP developers, but guys go read the PHP SPL
Peer review can help catch that kind of thing. If you have another developer looking at the code, and they continually find implementations of standard library methods, it should fail the review unless there's a good reason for reinventing the wheel.
Young, ambitious programmers like to solve every problem on their own. They don't need no stinkin' libraries. Older, lazy programmers would rather search for existing solutions to the problem at hand.
So my advice: the next time you hire a programmer, choose the old guy who falls asleep in the reception area.
Just kidding, mostly. Peer review and education is the answer.
Better search techniques. and Domain Specific Familiarity
How does a developer check for a function they dont know the name of? Or perhaps there isnt an EXACT built in function to do what they want, but something they can use to save a lot of code. You need to be able to find the right terminology for the problem at hand, and from there you know what to search for. This is best achived by reading topics specific to your problem domain. Get away from coding specific resources and spend sometime in the field which you are coding for... wether it be retail, medical, insurance, etc.
Summary: Assumption is the mother of all FUBARs
I see this a lot from colleagues who are unfamiliar with the concept of frameworks (god how they complain about "two languages in one"), to wit: old C++ guys suddenly confronted with C# diving in head first to recreate hashtables from scratch...
Clearly a big part of this phenomenon from that angle is not stepping out of old mindsets and habits. If you're in a new environment you need to learn the new rules. The only way to deal with that from the outside looking in is to provide training, whether that's pair-programming for a while or something more formal.
Lack of familiarity with your tools breeds the contempt of others.
A simple coding style document might help by reminding the devs that there are libraries available (maybe list some preferred) and that they should be familiar with them.
Sometimes, you just have to remind people.
A peer review would help.
PHP is well documented if and only if, you know exactly what you're looking for. For example, you'd open Arrays and Array functions sections to see what you can do with arrays. And guess what, there is not even mention of SPL.
You should also encourage research before actually setting out on writing code. I usually approach problems by thinking about a way to do it, then I try to find anything in the standard library or any other libraries that will help me out. I'd say that an hour of research in some cases can be worth days of coding.
If people aren't doing this, it may be a good idea to have someone ask them questions about their general approach to the problem and what library functions/classes they are thinking about using. If they're missing something obvious, suggest it to them.
Two reasons pop to mind quickly. First, the Standard PHP Library isn't WELL known, and suffers from poor documentation. The php.net website is widely considered the language's best asset, but a lot of the newer built in classes (such as the SPL, reflection API, DomDocument, etc.) are little more than a list of methods without a lot of context.
More importantly though, it looks like the full SPL never shipped by default with any version of PHP prior to the (unreleased) 5.3. This is a killer as far as adoption goes. Usually people writing PHP code don't have control over what gets complied into their PHP binary. That's handled by their web-host and/or operations team, and web hosts and/or operations teams have different goals than a developer and aren't going to install every optional extension that comes along. This also means projects like Drupal, Joomla, Wordpress, etc. can't rely on the SPL being installed everywhere, so they don't use it.
Part of the reason PHP "won out" over perl was a single install had everything you ever needed. Optional extensions have never become widely adopted until they became part of the base install.
Very hard question to answer. Obviously peer review helps, but also proper documentation. Do your projects have technical specs, where you map out the classes and intefaces to be created?
If so, someone else on the team should review the specs and point out where existing code could be used...
Agree with training and peer review, but also enforcing unit testing and code documentation should help with the NIH syndrome :)