ManiaLib\Manialink: our (new) PHP lib for building XML

Open source, lightweight PHP framework for Manialink and Web development.

Moderator: NADEO

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

ManiaLib\Manialink: our (new) PHP lib for building XML

Post by gouxim »

Much hello,

We are working on a new version of ManiaLib (PHP framework for manialinks). In order to make things simplier, it will be split in several standalone packages (like Symfony components).

The first package we're working on is the evolution of ManiaLib\Gui and is made for building the actual XML of manialink pages.

We are keeping some stuff from ManiaLib\Gui, but are still starting from scratch and breaking most of the compatibility, so don't expect to easilly convert old Manialib code to this new lib.

The good news is that it uses a new namespace (ManiaLib\Manialink) so you can actually use both at the same time without conflict if you'd like.

As stated above, ManiaLib\Manialink is standalone. It is made for abstracting XML. Therefore you can use it wherever you fancy, from Web apps (typically manialinks) to controllers (eg. ManiaLive).

Installation is easy with composer, and usage, after a bit of learning, should feel confortable and logical.

It's a work in progress. Although functionnal, it lacks some classes and methods. We will break things without notice. Still, we think working on it openly on github is a nice way to do. We can also consider suggestions for features.

https://github.com/maniaplanet/manialib-manialink

I'll be glad to answer questions you might have!
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
Fadden
Posts: 181
Joined: 10 May 2011, 18:21

Re: ManiaLib\Manialink: PHP lib for building XML

Post by Fadden »

I have a question :D :
- Why making a new version from scratch whereas the current version seems to work correctly?
Elle est où la poulette ?
User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: ManiaLib\Manialink: PHP lib for building XML

Post by gouxim »

I started ManiaLib when i was an intern back in 2008. While it works very well, we've been working with it daily for the past 5 years, so we have a very clear vision of what's working and what's cumbersome or not working. Starting from scratch allows to break whatever we want, build a very clean and logical architecture. It also helps moving faster.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
m4rcel
Posts: 653
Joined: 15 Jun 2010, 11:12
Contact:

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by m4rcel »

Starting from scratch sometimes is the best way to improve a project. I know this from my own projects ^^


I looked through the code, and I have some suggestions on how you can improve the quality of it and to make it easier to understand and thus to use.

1. Add PHP Docblocks

It is important, that you start adding all the PHP-Docblocks. Because if you do not add them right at the beginning, you will never add them at all. It will not only help others understanding your code, it will also help yourself when you return to old code after some months, as you may have forgotten what it does.

Most important is that return types and incoming parameter types are named in the docblocks. PHP has a weak type safety, this makes the documentation of the types even more important. For example in the Elements classes, the return types are already defined (helping the IDE providing the autocomplete), yet not a single incoming parameter type has been specified. What does Label->setAutonewline() expect? A boolean (as it is a flag of the label), or a string (as it will be an XML attribute in the end)?

I also saw the following docblock:

Code: Select all

	/**
	 * Returns the X position of an element in relation to another element and
	 * according to their respective alignments
	 * 
	 * @param int X position of the parent element
	 * @param int Width of the parent element
	 * @param string Horizontal alignement of the parent element
	 * @param string Horizontal alignement of the element you want to place
	 * @return int Calculated X position of the element you want to place
	 */
	final public static function getAlignedPosX($posX, $sizeX, $halign, $newAlign)
While a valid docblock in other languages, a PHP Docblock requires the parameter name to be written into the @param line. So this block should look like:

Code: Select all

	/**
	 * Returns the X position of an element in relation to another element and
	 * according to their respective alignments
	 * 
	 * @param int $posX X position of the parent element
	 * @param int $sizeX Width of the parent element
	 * @param string $halign Horizontal alignement of the parent element
	 * @param string $newAlign Horizontal alignement of the element you want to place
	 * @return int Calculated X position of the element you want to place
	 */
	final public static function getAlignedPosX($posX, $sizeX, $halign, $newAlign)
Take the time for adding and correcting the docblocks -- It will help in the future ;)

2. No Public Properties

I think it is no secret that public properties should be avoided. Yet Cards\Box and Cards\LabelBox have public ->bg and ->label. As soon as I set one of these properties to something other than Node instances, I think ManiaLib will break somewhere. Provide Setters and Getters as you did in the other classes to refuse setting wrong values to the properties.

So when you are already breaking old code, then use this situation to remove the public properties ^^

3. Bad Example

The last one is more a personal preference.

On github, you have the following example code:

Code: Select all

$ui = LabelBox::create()
    ->setPosn(0, -35)
    ->setSizen(100, 10)
    ->appendTo($frame)
    ->bg
    ->setStyle(Bgs1::BgTitle3)
    ->getParent()
    ->label
    ->setText('Much foobar')
    ->setTextSize(4)
    ->getParent()
    ->appendTo($frame);
While using fluent interface is nice, you switch the context several times in this code block. With ->bg you go to the background element to set the style, and then return with getParent() to the original one, and do that again with ->label.
In my opinion, the following, while a little longer, makes clearer what happens:

Code: Select all

$ui = LabelBox::create()
    ->setPosn(0, -35)
    ->setSizen(100, 10)
    ->appendTo($frame);
$ui->bg->setStyle(Bgs1::BgTitle3);
$ui->label->setText('Much foobar')
          ->setTextSize(4)
$ui->appendTo($frame);
Maybe with this you notice that $ui gets appended twice to $frame?
ImageImage
Image
User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by gouxim »

Thanks for you feedback!
m4rcel wrote:1. Add PHP Docblocks
Yep, it's planned. Right now i'm focusing on the code itelf to move faster since MP3 is our priority. But obviously i'd like to document the code to generate a nice doc.
m4rcel wrote:2. No Public Properties
I agree that theoretically it's bad. But it's a tradeoff for simplicity's sake. I might add getters on those open source objects to have a cleaner project, even if we keep on using public props in our own cards internally.
m4rcel wrote:3. Bad Example
I agree. It was a quick and dirty example to see if it worked, but i would probably write it like you did.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by gouxim »

Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
TheM
Posts: 1446
Joined: 15 Jun 2010, 14:30
Location: Uden, Noord-Brabant, Netherlands
Contact:

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by TheM »

gouxim wrote:
m4rcel wrote:1. Add PHP Docblocks
Yep, it's planned. Right now i'm focusing on the code itelf to move faster since MP3 is our priority. But obviously i'd like to document the code to generate a nice doc.
Why don't make documentation while you're coding?
It makes coding easier and making the documentation quicker ...
Global moderator | Dutch moderator | Laddermoderator | ManiaWiki moderator
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by gouxim »

TheM wrote:Why don't make documentation while you're coding?
gouxim wrote:focusing on the code itelf to move faster since MP3 is our priority
TheM wrote:It makes coding easier
Nop it does not ^^
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
TheM
Posts: 1446
Joined: 15 Jun 2010, 14:30
Location: Uden, Noord-Brabant, Netherlands
Contact:

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by TheM »

gouxim wrote:Nop it does not ^^
Then I suppose you're not doing it right ...
Global moderator | Dutch moderator | Laddermoderator | ManiaWiki moderator
Server Manager/webmaster of Smurfen.net, join us on Canyon, Valley and Royal!
ESL (Game) Staff Head for TrackMania (Stadium, Canyon and Valley).
User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: ManiaLib\Manialink: our (new) PHP lib for building XML

Post by gouxim »

Short answer: it is a bit presumptuous from you to say this ;)

Longer answer: I work with manialib on a daily basis, i have written it, and i work with netbeans which provides code hints and completion. So in the end, documenting it will not make coding easier for me. It will just be more things to write and maintain.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
Post Reply

Return to “ManiaLib”

Who is online

Users browsing this forum: No registered users and 1 guest