repository refactored to have the same behavior as before, added paginator support
minnor fixes, added PhpDocs