universe is the list of knowable codes, tools, add-ons, integrations, etc for CiviCRM. The
- The standard CiviCRM git repositories (
- Any extensions registered on
civicrm.orgthat have a Git URL.
- Most infrastructure and supporting components behind
universe can help you analyze the technical state of the CiviCRM community's code. For example, suppose you want to change the
signature of a function in
getContactDetails(...). You can get a copy of the universe and search the entire
source tree for
getContactDetails to see how it's being used.
Use a fast network and fast storage device (SSD)
universe is fairly big. (At time of writing, ~2 GB.) A fast network will help with downloading, and a fast storage will help
Create the universe¶
If your system is configured to support civibuild, then simply run:
$ civibuild create universe
Alternatively, if you have a copy of
buildkit but don't use
civibuild, then run:
$ mkdir ~/src/universe $ fetch-universe ~/src/universe
Search the universe¶
Note the path to your copy (eg
cd to it.
$ cd ~/buildkit/build/universe
You can get a lot of information with standard Unix tools like
$ grep -r getContactDetails .
There's a lot you can do with
grep, such as:
# Case insensitive search $ grep -ri getContactDetails . # Ignore folders like `.git` or `.svn` $ grep -r --exclude-dir=.git --exclude-dir=.svn getContactDetails . # Edit all matching files $ vi $(grep -ril getContactDetails .)
Why would you search
Continuing the example, you might argue, "
getContactDetails isn't officially an API, so it's fair-game to change whenever we want.
Searching the universe doesn't add anything."
In policy terms, that might be right... but is it really a safe change in practical terms? Most of the time... probably! But
some of the time, Murphy's Law kicks in -- changing
getContactDetails(...) might break 10 extensions. Arguably, the fault lies with
the extension author who called a non-API -- but that will bring little comfort to the 20 users who show up on StackExchange asking for
help, and it will still reflect badly on all of us.
universe is a simple way to get ahead of that risk -- and to make decisions based on empirical data rather than
What to do if searching
universe reveals a technical conflict?
universe is just a tool -- it's a way to get ahead of problems (by making them easier to discover). It's not an over-arching policy on
what to do if you find a conflict. Returning to our
- Maybe you should change the approach -- keep the signature of
getContactDetailsas-is, but change something else.
- Or maybe the extensions should be updated to match the new signature.
- Or maybe you should give a heads-up to the other affected developers.
We're not trying to pre-judge the solution here. Main advice: start from the assumption that this is a shared problem. Finding a solution is good for you, for the other developers, and for the users. Encourage others to view it the same way.
Update the universe¶
universe is ever-expanding -- eg projects are updated, and new projects are added. Generally, it's not important to be accurate
"up-to-the-minute". But you may want to update if your copy of the universe is more than a week or two old.
Simply note the path to your copy (eg
~/src/universe) and run
$ fetch-universe ~/buildkit/build/universe